reactivity.d.ts 11 KB

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