reactivity.d.ts 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350
  1. import { IfAny } from '@vue/shared';
  2. declare type BaseTypes = string | number | boolean;
  3. declare type Builtin = Primitive | Function | Date | Error | RegExp;
  4. declare type CollectionTypes = IterableCollections | WeakCollections;
  5. export declare function computed<T>(getter: ComputedGetter<T>, debugOptions?: DebuggerOptions): ComputedRef<T>;
  6. export declare function computed<T>(options: WritableComputedOptions<T>, debugOptions?: DebuggerOptions): WritableComputedRef<T>;
  7. export declare type ComputedGetter<T> = (...args: any[]) => T;
  8. export declare interface ComputedRef<T = any> extends WritableComputedRef<T> {
  9. readonly value: T;
  10. [ComputedRefSymbol]: true;
  11. }
  12. declare class ComputedRefImpl<T> {
  13. private readonly _setter;
  14. dep?: Dep;
  15. private _value;
  16. readonly effect: ReactiveEffect<T>;
  17. readonly __v_isRef = true;
  18. readonly [ReactiveFlags.IS_READONLY]: boolean;
  19. _dirty: boolean;
  20. _cacheable: boolean;
  21. constructor(getter: ComputedGetter<T>, _setter: ComputedSetter<T>, isReadonly: boolean, isSSR: boolean);
  22. get value(): T;
  23. set value(newValue: T);
  24. }
  25. declare const ComputedRefSymbol: unique symbol;
  26. export declare type ComputedSetter<T> = (v: T) => void;
  27. export declare function customRef<T>(factory: CustomRefFactory<T>): Ref<T>;
  28. export declare type CustomRefFactory<T> = (track: () => void, trigger: () => void) => {
  29. get: () => T;
  30. set: (value: T) => void;
  31. };
  32. export declare type DebuggerEvent = {
  33. effect: ReactiveEffect;
  34. } & DebuggerEventExtraInfo;
  35. export declare type DebuggerEventExtraInfo = {
  36. target: object;
  37. type: TrackOpTypes | TriggerOpTypes;
  38. key: any;
  39. newValue?: any;
  40. oldValue?: any;
  41. oldTarget?: Map<any, any> | Set<any>;
  42. };
  43. export declare interface DebuggerOptions {
  44. onTrack?: (event: DebuggerEvent) => void;
  45. onTrigger?: (event: DebuggerEvent) => void;
  46. }
  47. export declare type DeepReadonly<T> = T extends Builtin ? T : T extends Map<infer K, infer V> ? ReadonlyMap<DeepReadonly<K>, DeepReadonly<V>> : T extends ReadonlyMap<infer K, infer V> ? ReadonlyMap<DeepReadonly<K>, DeepReadonly<V>> : T extends WeakMap<infer K, infer V> ? WeakMap<DeepReadonly<K>, DeepReadonly<V>> : T extends Set<infer U> ? ReadonlySet<DeepReadonly<U>> : T extends ReadonlySet<infer U> ? ReadonlySet<DeepReadonly<U>> : T extends WeakSet<infer U> ? WeakSet<DeepReadonly<U>> : T extends Promise<infer U> ? Promise<DeepReadonly<U>> : T extends Ref<infer U> ? Readonly<Ref<DeepReadonly<U>>> : T extends {} ? {
  48. readonly [K in keyof T]: DeepReadonly<T[K]>;
  49. } : Readonly<T>;
  50. export declare function deferredComputed<T>(getter: () => T): ComputedRef<T>;
  51. declare type Dep = Set<ReactiveEffect> & TrackedMarkers;
  52. export declare function effect<T = any>(fn: () => T, options?: ReactiveEffectOptions): ReactiveEffectRunner;
  53. export declare type EffectScheduler = (...args: any[]) => any;
  54. export declare class EffectScope {
  55. detached: boolean;
  56. /* Excluded from this release type: active */
  57. /* Excluded from this release type: effects */
  58. /* Excluded from this release type: cleanups */
  59. /* Excluded from this release type: parent */
  60. /* Excluded from this release type: scopes */
  61. /* Excluded from this release type: index */
  62. constructor(detached?: boolean);
  63. run<T>(fn: () => T): T | undefined;
  64. /* Excluded from this release type: on */
  65. /* Excluded from this release type: off */
  66. stop(fromParent?: boolean): void;
  67. }
  68. export declare function effectScope(detached?: boolean): EffectScope;
  69. export declare function enableTracking(): void;
  70. export declare function getCurrentScope(): EffectScope | undefined;
  71. export declare function isProxy(value: unknown): boolean;
  72. export declare function isReactive(value: unknown): boolean;
  73. export declare function isReadonly(value: unknown): boolean;
  74. export declare function isRef<T>(r: Ref<T> | unknown): r is Ref<T>;
  75. export declare function isShallow(value: unknown): boolean;
  76. declare type IterableCollections = Map<any, any> | Set<any>;
  77. export declare const ITERATE_KEY: unique symbol;
  78. export declare function markRaw<T extends object>(value: T): Raw<T>;
  79. export declare function onScopeDispose(fn: () => void): void;
  80. export declare function pauseTracking(): void;
  81. declare type Primitive = string | number | boolean | bigint | symbol | undefined | null;
  82. export declare function proxyRefs<T extends object>(objectWithRefs: T): ShallowUnwrapRef<T>;
  83. export declare type Raw<T> = T & {
  84. [RawSymbol]?: true;
  85. };
  86. declare const RawSymbol: unique symbol;
  87. /**
  88. * Creates a reactive copy of the original object.
  89. *
  90. * The reactive conversion is "deep"—it affects all nested properties. In the
  91. * ES2015 Proxy based implementation, the returned proxy is **not** equal to the
  92. * original object. It is recommended to work exclusively with the reactive
  93. * proxy and avoid relying on the original object.
  94. *
  95. * A reactive object also automatically unwraps refs contained in it, so you
  96. * don't need to use `.value` when accessing and mutating their value:
  97. *
  98. * ```js
  99. * const count = ref(0)
  100. * const obj = reactive({
  101. * count
  102. * })
  103. *
  104. * obj.count++
  105. * obj.count // -> 1
  106. * count.value // -> 1
  107. * ```
  108. */
  109. export declare function reactive<T extends object>(target: T): UnwrapNestedRefs<T>;
  110. export declare class ReactiveEffect<T = any> {
  111. fn: () => T;
  112. scheduler: EffectScheduler | null;
  113. active: boolean;
  114. deps: Dep[];
  115. parent: ReactiveEffect | undefined;
  116. /* Excluded from this release type: computed */
  117. /* Excluded from this release type: allowRecurse */
  118. /* Excluded from this release type: deferStop */
  119. onStop?: () => void;
  120. onTrack?: (event: DebuggerEvent) => void;
  121. onTrigger?: (event: DebuggerEvent) => void;
  122. constructor(fn: () => T, scheduler?: EffectScheduler | null, scope?: EffectScope);
  123. run(): T | undefined;
  124. stop(): void;
  125. }
  126. export declare interface ReactiveEffectOptions extends DebuggerOptions {
  127. lazy?: boolean;
  128. scheduler?: EffectScheduler;
  129. scope?: EffectScope;
  130. allowRecurse?: boolean;
  131. onStop?: () => void;
  132. }
  133. export declare interface ReactiveEffectRunner<T = any> {
  134. (): T;
  135. effect: ReactiveEffect;
  136. }
  137. export declare const enum ReactiveFlags {
  138. SKIP = "__v_skip",
  139. IS_REACTIVE = "__v_isReactive",
  140. IS_READONLY = "__v_isReadonly",
  141. IS_SHALLOW = "__v_isShallow",
  142. RAW = "__v_raw"
  143. }
  144. /**
  145. * Creates a readonly copy of the original object. Note the returned copy is not
  146. * made reactive, but `readonly` can be called on an already reactive object.
  147. */
  148. export declare function readonly<T extends object>(target: T): DeepReadonly<UnwrapNestedRefs<T>>;
  149. export declare interface Ref<T = any> {
  150. value: T;
  151. /**
  152. * Type differentiator only.
  153. * We need this to be in public d.ts but don't want it to show up in IDE
  154. * autocomplete, so we use a private Symbol instead.
  155. */
  156. [RefSymbol]: true;
  157. }
  158. export declare function ref<T extends object>(value: T): [T] extends [Ref] ? T : Ref<UnwrapRef<T>>;
  159. export declare function ref<T>(value: T): Ref<UnwrapRef<T>>;
  160. export declare function ref<T = any>(): Ref<T | undefined>;
  161. declare const RefSymbol: unique symbol;
  162. /**
  163. * This is a special exported interface for other packages to declare
  164. * additional types that should bail out for ref unwrapping. For example
  165. * \@vue/runtime-dom can declare it like so in its d.ts:
  166. *
  167. * ``` ts
  168. * declare module '@vue/reactivity' {
  169. * export interface RefUnwrapBailTypes {
  170. * runtimeDOMBailTypes: Node | Window
  171. * }
  172. * }
  173. * ```
  174. *
  175. * Note that api-extractor somehow refuses to include `declare module`
  176. * augmentations in its generated d.ts, so we have to manually append them
  177. * to the final generated d.ts in our build process.
  178. */
  179. export declare interface RefUnwrapBailTypes {
  180. }
  181. export declare function resetTracking(): void;
  182. export declare type ShallowReactive<T> = T & {
  183. [ShallowReactiveMarker]?: true;
  184. };
  185. /**
  186. * Return a shallowly-reactive copy of the original object, where only the root
  187. * level properties are reactive. It also does not auto-unwrap refs (even at the
  188. * root level).
  189. */
  190. export declare function shallowReactive<T extends object>(target: T): ShallowReactive<T>;
  191. declare const ShallowReactiveMarker: unique symbol;
  192. /**
  193. * Returns a reactive-copy of the original object, where only the root level
  194. * properties are readonly, and does NOT unwrap refs nor recursively convert
  195. * returned properties.
  196. * This is used for creating the props proxy object for stateful components.
  197. */
  198. export declare function shallowReadonly<T extends object>(target: T): Readonly<T>;
  199. export declare type ShallowRef<T = any> = Ref<T> & {
  200. [ShallowRefMarker]?: true;
  201. };
  202. export declare function shallowRef<T extends object>(value: T): T extends Ref ? T : ShallowRef<T>;
  203. export declare function shallowRef<T>(value: T): ShallowRef<T>;
  204. export declare function shallowRef<T = any>(): ShallowRef<T | undefined>;
  205. declare const ShallowRefMarker: unique symbol;
  206. export declare type ShallowUnwrapRef<T> = {
  207. [K in keyof T]: T[K] extends Ref<infer V> ? V : T[K] extends Ref<infer V> | undefined ? unknown extends V ? undefined : V | undefined : T[K];
  208. };
  209. declare function stop_2(runner: ReactiveEffectRunner): void;
  210. export { stop_2 as stop }
  211. export declare function toRaw<T>(observed: T): T;
  212. export declare type ToRef<T> = IfAny<T, Ref<T>, [T] extends [Ref] ? T : Ref<T>>;
  213. export declare function toRef<T extends object, K extends keyof T>(object: T, key: K): ToRef<T[K]>;
  214. export declare function toRef<T extends object, K extends keyof T>(object: T, key: K, defaultValue: T[K]): ToRef<Exclude<T[K], undefined>>;
  215. export declare type ToRefs<T = any> = {
  216. [K in keyof T]: ToRef<T[K]>;
  217. };
  218. export declare function toRefs<T extends object>(object: T): ToRefs<T>;
  219. export declare function track(target: object, type: TrackOpTypes, key: unknown): void;
  220. /**
  221. * wasTracked and newTracked maintain the status for several levels of effect
  222. * tracking recursion. One bit per level is used to define whether the dependency
  223. * was/is tracked.
  224. */
  225. declare type TrackedMarkers = {
  226. /**
  227. * wasTracked
  228. */
  229. w: number;
  230. /**
  231. * newTracked
  232. */
  233. n: number;
  234. };
  235. export declare const enum TrackOpTypes {
  236. GET = "get",
  237. HAS = "has",
  238. ITERATE = "iterate"
  239. }
  240. export declare function trigger(target: object, type: TriggerOpTypes, key?: unknown, newValue?: unknown, oldValue?: unknown, oldTarget?: Map<unknown, unknown> | Set<unknown>): void;
  241. export declare const enum TriggerOpTypes {
  242. SET = "set",
  243. ADD = "add",
  244. DELETE = "delete",
  245. CLEAR = "clear"
  246. }
  247. export declare function triggerRef(ref: Ref): void;
  248. export declare function unref<T>(ref: T | Ref<T>): T;
  249. export declare type UnwrapNestedRefs<T> = T extends Ref ? T : UnwrapRefSimple<T>;
  250. export declare type UnwrapRef<T> = T extends ShallowRef<infer V> ? V : T extends Ref<infer V> ? UnwrapRefSimple<V> : UnwrapRefSimple<T>;
  251. declare type UnwrapRefSimple<T> = T extends Function | CollectionTypes | BaseTypes | Ref | RefUnwrapBailTypes[keyof RefUnwrapBailTypes] | {
  252. [RawSymbol]?: true;
  253. } ? T : T extends ReadonlyArray<any> ? {
  254. [K in keyof T]: UnwrapRefSimple<T[K]>;
  255. } : T extends object & {
  256. [ShallowReactiveMarker]?: never;
  257. } ? {
  258. [P in keyof T]: P extends symbol ? T[P] : UnwrapRef<T[P]>;
  259. } : T;
  260. declare type WeakCollections = WeakMap<any, any> | WeakSet<any>;
  261. export declare interface WritableComputedOptions<T> {
  262. get: ComputedGetter<T>;
  263. set: ComputedSetter<T>;
  264. }
  265. export declare interface WritableComputedRef<T> extends Ref<T> {
  266. readonly effect: ReactiveEffect<T>;
  267. }
  268. export { }