reactivity.d.ts 27 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756
  1. import { IfAny } from '@vue/shared';
  2. export declare enum TrackOpTypes {
  3. GET = "get",
  4. HAS = "has",
  5. ITERATE = "iterate"
  6. }
  7. export declare enum TriggerOpTypes {
  8. SET = "set",
  9. ADD = "add",
  10. DELETE = "delete",
  11. CLEAR = "clear"
  12. }
  13. export declare enum ReactiveFlags {
  14. SKIP = "__v_skip",
  15. IS_REACTIVE = "__v_isReactive",
  16. IS_READONLY = "__v_isReadonly",
  17. IS_SHALLOW = "__v_isShallow",
  18. RAW = "__v_raw",
  19. IS_REF = "__v_isRef"
  20. }
  21. export type UnwrapNestedRefs<T> = T extends Ref ? T : UnwrapRefSimple<T>;
  22. declare const ReactiveMarkerSymbol: unique symbol;
  23. export interface ReactiveMarker {
  24. [ReactiveMarkerSymbol]?: void;
  25. }
  26. export type Reactive<T> = UnwrapNestedRefs<T> & (T extends readonly any[] ? ReactiveMarker : {});
  27. /**
  28. * Returns a reactive proxy of the object.
  29. *
  30. * The reactive conversion is "deep": it affects all nested properties. A
  31. * reactive object also deeply unwraps any properties that are refs while
  32. * maintaining reactivity.
  33. *
  34. * @example
  35. * ```js
  36. * const obj = reactive({ count: 0 })
  37. * ```
  38. *
  39. * @param target - The source object.
  40. * @see {@link https://vuejs.org/api/reactivity-core.html#reactive}
  41. */
  42. export declare function reactive<T extends object>(target: T): Reactive<T>;
  43. declare class ShallowReactiveBrandClass {
  44. private __shallowReactiveBrand?;
  45. }
  46. type ShallowReactiveBrand = ShallowReactiveBrandClass;
  47. export type ShallowReactive<T> = T & ShallowReactiveBrand;
  48. /**
  49. * Shallow version of {@link reactive}.
  50. *
  51. * Unlike {@link reactive}, there is no deep conversion: only root-level
  52. * properties are reactive for a shallow reactive object. Property values are
  53. * stored and exposed as-is - this also means properties with ref values will
  54. * not be automatically unwrapped.
  55. *
  56. * @example
  57. * ```js
  58. * const state = shallowReactive({
  59. * foo: 1,
  60. * nested: {
  61. * bar: 2
  62. * }
  63. * })
  64. *
  65. * // mutating state's own properties is reactive
  66. * state.foo++
  67. *
  68. * // ...but does not convert nested objects
  69. * isReactive(state.nested) // false
  70. *
  71. * // NOT reactive
  72. * state.nested.bar++
  73. * ```
  74. *
  75. * @param target - The source object.
  76. * @see {@link https://vuejs.org/api/reactivity-advanced.html#shallowreactive}
  77. */
  78. export declare function shallowReactive<T extends object>(target: T): ShallowReactive<T>;
  79. type Primitive = string | number | boolean | bigint | symbol | undefined | null;
  80. type Builtin = Primitive | Function | Date | Error | RegExp;
  81. export 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, unknown> ? Readonly<Ref<DeepReadonly<U>>> : T extends {} ? {
  82. readonly [K in keyof T]: DeepReadonly<T[K]>;
  83. } : Readonly<T>;
  84. /**
  85. * Takes an object (reactive or plain) or a ref and returns a readonly proxy to
  86. * the original.
  87. *
  88. * A readonly proxy is deep: any nested property accessed will be readonly as
  89. * well. It also has the same ref-unwrapping behavior as {@link reactive},
  90. * except the unwrapped values will also be made readonly.
  91. *
  92. * @example
  93. * ```js
  94. * const original = reactive({ count: 0 })
  95. *
  96. * const copy = readonly(original)
  97. *
  98. * watchEffect(() => {
  99. * // works for reactivity tracking
  100. * console.log(copy.count)
  101. * })
  102. *
  103. * // mutating original will trigger watchers relying on the copy
  104. * original.count++
  105. *
  106. * // mutating the copy will fail and result in a warning
  107. * copy.count++ // warning!
  108. * ```
  109. *
  110. * @param target - The source object.
  111. * @see {@link https://vuejs.org/api/reactivity-core.html#readonly}
  112. */
  113. export declare function readonly<T extends object>(target: T): DeepReadonly<UnwrapNestedRefs<T>>;
  114. /**
  115. * Shallow version of {@link readonly}.
  116. *
  117. * Unlike {@link readonly}, there is no deep conversion: only root-level
  118. * properties are made readonly. Property values are stored and exposed as-is -
  119. * this also means properties with ref values will not be automatically
  120. * unwrapped.
  121. *
  122. * @example
  123. * ```js
  124. * const state = shallowReadonly({
  125. * foo: 1,
  126. * nested: {
  127. * bar: 2
  128. * }
  129. * })
  130. *
  131. * // mutating state's own properties will fail
  132. * state.foo++
  133. *
  134. * // ...but works on nested objects
  135. * isReadonly(state.nested) // false
  136. *
  137. * // works
  138. * state.nested.bar++
  139. * ```
  140. *
  141. * @param target - The source object.
  142. * @see {@link https://vuejs.org/api/reactivity-advanced.html#shallowreadonly}
  143. */
  144. export declare function shallowReadonly<T extends object>(target: T): Readonly<T>;
  145. /**
  146. * Checks if an object is a proxy created by {@link reactive} or
  147. * {@link shallowReactive} (or {@link ref} in some cases).
  148. *
  149. * @example
  150. * ```js
  151. * isReactive(reactive({})) // => true
  152. * isReactive(readonly(reactive({}))) // => true
  153. * isReactive(ref({}).value) // => true
  154. * isReactive(readonly(ref({})).value) // => true
  155. * isReactive(ref(true)) // => false
  156. * isReactive(shallowRef({}).value) // => false
  157. * isReactive(shallowReactive({})) // => true
  158. * ```
  159. *
  160. * @param value - The value to check.
  161. * @see {@link https://vuejs.org/api/reactivity-utilities.html#isreactive}
  162. */
  163. export declare function isReactive(value: unknown): boolean;
  164. /**
  165. * Checks whether the passed value is a readonly object. The properties of a
  166. * readonly object can change, but they can't be assigned directly via the
  167. * passed object.
  168. *
  169. * The proxies created by {@link readonly} and {@link shallowReadonly} are
  170. * both considered readonly, as is a computed ref without a set function.
  171. *
  172. * @param value - The value to check.
  173. * @see {@link https://vuejs.org/api/reactivity-utilities.html#isreadonly}
  174. */
  175. export declare function isReadonly(value: unknown): boolean;
  176. export declare function isShallow(value: unknown): boolean;
  177. /**
  178. * Checks if an object is a proxy created by {@link reactive},
  179. * {@link readonly}, {@link shallowReactive} or {@link shallowReadonly}.
  180. *
  181. * @param value - The value to check.
  182. * @see {@link https://vuejs.org/api/reactivity-utilities.html#isproxy}
  183. */
  184. export declare function isProxy(value: any): boolean;
  185. /**
  186. * Returns the raw, original object of a Vue-created proxy.
  187. *
  188. * `toRaw()` can return the original object from proxies created by
  189. * {@link reactive}, {@link readonly}, {@link shallowReactive} or
  190. * {@link shallowReadonly}.
  191. *
  192. * This is an escape hatch that can be used to temporarily read without
  193. * incurring proxy access / tracking overhead or write without triggering
  194. * changes. It is **not** recommended to hold a persistent reference to the
  195. * original object. Use with caution.
  196. *
  197. * @example
  198. * ```js
  199. * const foo = {}
  200. * const reactiveFoo = reactive(foo)
  201. *
  202. * console.log(toRaw(reactiveFoo) === foo) // true
  203. * ```
  204. *
  205. * @param observed - The object for which the "raw" value is requested.
  206. * @see {@link https://vuejs.org/api/reactivity-advanced.html#toraw}
  207. */
  208. export declare function toRaw<T>(observed: T): T;
  209. export type Raw<T> = T & {
  210. [RawSymbol]?: true;
  211. };
  212. /**
  213. * Marks an object so that it will never be converted to a proxy. Returns the
  214. * object itself.
  215. *
  216. * @example
  217. * ```js
  218. * const foo = markRaw({})
  219. * console.log(isReactive(reactive(foo))) // false
  220. *
  221. * // also works when nested inside other reactive objects
  222. * const bar = reactive({ foo })
  223. * console.log(isReactive(bar.foo)) // false
  224. * ```
  225. *
  226. * **Warning:** `markRaw()` together with the shallow APIs such as
  227. * {@link shallowReactive} allow you to selectively opt-out of the default
  228. * deep reactive/readonly conversion and embed raw, non-proxied objects in your
  229. * state graph.
  230. *
  231. * @param value - The object to be marked as "raw".
  232. * @see {@link https://vuejs.org/api/reactivity-advanced.html#markraw}
  233. */
  234. export declare function markRaw<T extends object>(value: T): Raw<T>;
  235. /**
  236. * Returns a reactive proxy of the given value (if possible).
  237. *
  238. * If the given value is not an object, the original value itself is returned.
  239. *
  240. * @param value - The value for which a reactive proxy shall be created.
  241. */
  242. export declare const toReactive: <T extends unknown>(value: T) => T;
  243. /**
  244. * Returns a readonly proxy of the given value (if possible).
  245. *
  246. * If the given value is not an object, the original value itself is returned.
  247. *
  248. * @param value - The value for which a readonly proxy shall be created.
  249. */
  250. export declare const toReadonly: <T extends unknown>(value: T) => DeepReadonly<T>;
  251. export type EffectScheduler = (...args: any[]) => any;
  252. export type DebuggerEvent = {
  253. effect: Subscriber;
  254. } & DebuggerEventExtraInfo;
  255. export type DebuggerEventExtraInfo = {
  256. target: object;
  257. type: TrackOpTypes | TriggerOpTypes;
  258. key: any;
  259. newValue?: any;
  260. oldValue?: any;
  261. oldTarget?: Map<any, any> | Set<any>;
  262. };
  263. export interface DebuggerOptions {
  264. onTrack?: (event: DebuggerEvent) => void;
  265. onTrigger?: (event: DebuggerEvent) => void;
  266. }
  267. export interface ReactiveEffectOptions extends DebuggerOptions {
  268. scheduler?: EffectScheduler;
  269. allowRecurse?: boolean;
  270. onStop?: () => void;
  271. }
  272. export interface ReactiveEffectRunner<T = any> {
  273. (): T;
  274. effect: ReactiveEffect;
  275. }
  276. export declare enum EffectFlags {
  277. /**
  278. * ReactiveEffect only
  279. */
  280. ACTIVE = 1,
  281. RUNNING = 2,
  282. TRACKING = 4,
  283. NOTIFIED = 8,
  284. DIRTY = 16,
  285. ALLOW_RECURSE = 32,
  286. PAUSED = 64,
  287. EVALUATED = 128
  288. }
  289. /**
  290. * Subscriber is a type that tracks (or subscribes to) a list of deps.
  291. */
  292. interface Subscriber extends DebuggerOptions {
  293. }
  294. export declare class ReactiveEffect<T = any> implements Subscriber, ReactiveEffectOptions {
  295. fn: () => T;
  296. scheduler?: EffectScheduler;
  297. onStop?: () => void;
  298. onTrack?: (event: DebuggerEvent) => void;
  299. onTrigger?: (event: DebuggerEvent) => void;
  300. constructor(fn: () => T);
  301. pause(): void;
  302. resume(): void;
  303. run(): T;
  304. stop(): void;
  305. trigger(): void;
  306. get dirty(): boolean;
  307. }
  308. export declare function effect<T = any>(fn: () => T, options?: ReactiveEffectOptions): ReactiveEffectRunner<T>;
  309. /**
  310. * Stops the effect associated with the given runner.
  311. *
  312. * @param runner - Association with the effect to stop tracking.
  313. */
  314. export declare function stop(runner: ReactiveEffectRunner): void;
  315. /**
  316. * Temporarily pauses tracking.
  317. */
  318. export declare function pauseTracking(): void;
  319. /**
  320. * Re-enables effect tracking (if it was paused).
  321. */
  322. export declare function enableTracking(): void;
  323. /**
  324. * Resets the previous global effect tracking state.
  325. */
  326. export declare function resetTracking(): void;
  327. /**
  328. * Registers a cleanup function for the current active effect.
  329. * The cleanup function is called right before the next effect run, or when the
  330. * effect is stopped.
  331. *
  332. * Throws a warning if there is no current active effect. The warning can be
  333. * suppressed by passing `true` to the second argument.
  334. *
  335. * @param fn - the cleanup function to be registered
  336. * @param failSilently - if `true`, will not throw warning when called without
  337. * an active effect.
  338. */
  339. export declare function onEffectCleanup(fn: () => void, failSilently?: boolean): void;
  340. declare const ComputedRefSymbol: unique symbol;
  341. declare const WritableComputedRefSymbol: unique symbol;
  342. interface BaseComputedRef<T, S = T> extends Ref<T, S> {
  343. [ComputedRefSymbol]: true;
  344. /**
  345. * @deprecated computed no longer uses effect
  346. */
  347. effect: ComputedRefImpl;
  348. }
  349. export interface ComputedRef<T = any> extends BaseComputedRef<T> {
  350. readonly value: T;
  351. }
  352. export interface WritableComputedRef<T, S = T> extends BaseComputedRef<T, S> {
  353. [WritableComputedRefSymbol]: true;
  354. }
  355. export type ComputedGetter<T> = (oldValue?: T) => T;
  356. export type ComputedSetter<T> = (newValue: T) => void;
  357. export interface WritableComputedOptions<T, S = T> {
  358. get: ComputedGetter<T>;
  359. set: ComputedSetter<S>;
  360. }
  361. /**
  362. * @private exported by @vue/reactivity for Vue core use, but not exported from
  363. * the main vue package
  364. */
  365. export declare class ComputedRefImpl<T = any> implements Subscriber {
  366. fn: ComputedGetter<T>;
  367. private readonly setter;
  368. effect: this;
  369. onTrack?: (event: DebuggerEvent) => void;
  370. onTrigger?: (event: DebuggerEvent) => void;
  371. constructor(fn: ComputedGetter<T>, setter: ComputedSetter<T> | undefined, isSSR: boolean);
  372. get value(): T;
  373. set value(newValue: T);
  374. }
  375. /**
  376. * Takes a getter function and returns a readonly reactive ref object for the
  377. * returned value from the getter. It can also take an object with get and set
  378. * functions to create a writable ref object.
  379. *
  380. * @example
  381. * ```js
  382. * // Creating a readonly computed ref:
  383. * const count = ref(1)
  384. * const plusOne = computed(() => count.value + 1)
  385. *
  386. * console.log(plusOne.value) // 2
  387. * plusOne.value++ // error
  388. * ```
  389. *
  390. * ```js
  391. * // Creating a writable computed ref:
  392. * const count = ref(1)
  393. * const plusOne = computed({
  394. * get: () => count.value + 1,
  395. * set: (val) => {
  396. * count.value = val - 1
  397. * }
  398. * })
  399. *
  400. * plusOne.value = 1
  401. * console.log(count.value) // 0
  402. * ```
  403. *
  404. * @param getter - Function that produces the next value.
  405. * @param debugOptions - For debugging. See {@link https://vuejs.org/guide/extras/reactivity-in-depth.html#computed-debugging}.
  406. * @see {@link https://vuejs.org/api/reactivity-core.html#computed}
  407. */
  408. export declare function computed<T>(getter: ComputedGetter<T>, debugOptions?: DebuggerOptions): ComputedRef<T>;
  409. export declare function computed<T, S = T>(options: WritableComputedOptions<T, S>, debugOptions?: DebuggerOptions): WritableComputedRef<T, S>;
  410. declare const RefSymbol: unique symbol;
  411. declare const RawSymbol: unique symbol;
  412. export interface Ref<T = any, S = T> {
  413. get value(): T;
  414. set value(_: S);
  415. /**
  416. * Type differentiator only.
  417. * We need this to be in public d.ts but don't want it to show up in IDE
  418. * autocomplete, so we use a private Symbol instead.
  419. */
  420. [RefSymbol]: true;
  421. }
  422. /**
  423. * Checks if a value is a ref object.
  424. *
  425. * @param r - The value to inspect.
  426. * @see {@link https://vuejs.org/api/reactivity-utilities.html#isref}
  427. */
  428. export declare function isRef<T>(r: Ref<T> | unknown): r is Ref<T>;
  429. /**
  430. * Takes an inner value and returns a reactive and mutable ref object, which
  431. * has a single property `.value` that points to the inner value.
  432. *
  433. * @param value - The object to wrap in the ref.
  434. * @see {@link https://vuejs.org/api/reactivity-core.html#ref}
  435. */
  436. export declare function ref<T>(value: T): [T] extends [Ref] ? IfAny<T, Ref<T>, T> : Ref<UnwrapRef<T>, UnwrapRef<T> | T>;
  437. export declare function ref<T = any>(): Ref<T | undefined>;
  438. declare const ShallowRefMarker: unique symbol;
  439. export type ShallowRef<T = any, S = T> = Ref<T, S> & {
  440. [ShallowRefMarker]?: true;
  441. };
  442. /**
  443. * Shallow version of {@link ref}.
  444. *
  445. * @example
  446. * ```js
  447. * const state = shallowRef({ count: 1 })
  448. *
  449. * // does NOT trigger change
  450. * state.value.count = 2
  451. *
  452. * // does trigger change
  453. * state.value = { count: 2 }
  454. * ```
  455. *
  456. * @param value - The "inner value" for the shallow ref.
  457. * @see {@link https://vuejs.org/api/reactivity-advanced.html#shallowref}
  458. */
  459. export declare function shallowRef<T>(value: T): Ref extends T ? T extends Ref ? IfAny<T, ShallowRef<T>, T> : ShallowRef<T> : ShallowRef<T>;
  460. export declare function shallowRef<T = any>(): ShallowRef<T | undefined>;
  461. /**
  462. * Force trigger effects that depends on a shallow ref. This is typically used
  463. * after making deep mutations to the inner value of a shallow ref.
  464. *
  465. * @example
  466. * ```js
  467. * const shallow = shallowRef({
  468. * greet: 'Hello, world'
  469. * })
  470. *
  471. * // Logs "Hello, world" once for the first run-through
  472. * watchEffect(() => {
  473. * console.log(shallow.value.greet)
  474. * })
  475. *
  476. * // This won't trigger the effect because the ref is shallow
  477. * shallow.value.greet = 'Hello, universe'
  478. *
  479. * // Logs "Hello, universe"
  480. * triggerRef(shallow)
  481. * ```
  482. *
  483. * @param ref - The ref whose tied effects shall be executed.
  484. * @see {@link https://vuejs.org/api/reactivity-advanced.html#triggerref}
  485. */
  486. export declare function triggerRef(ref: Ref): void;
  487. export type MaybeRef<T = any> = T | Ref<T> | ShallowRef<T> | WritableComputedRef<T>;
  488. export type MaybeRefOrGetter<T = any> = MaybeRef<T> | ComputedRef<T> | (() => T);
  489. /**
  490. * Returns the inner value if the argument is a ref, otherwise return the
  491. * argument itself. This is a sugar function for
  492. * `val = isRef(val) ? val.value : val`.
  493. *
  494. * @example
  495. * ```js
  496. * function useFoo(x: number | Ref<number>) {
  497. * const unwrapped = unref(x)
  498. * // unwrapped is guaranteed to be number now
  499. * }
  500. * ```
  501. *
  502. * @param ref - Ref or plain value to be converted into the plain value.
  503. * @see {@link https://vuejs.org/api/reactivity-utilities.html#unref}
  504. */
  505. export declare function unref<T>(ref: MaybeRef<T> | ComputedRef<T>): T;
  506. /**
  507. * Normalizes values / refs / getters to values.
  508. * This is similar to {@link unref}, except that it also normalizes getters.
  509. * If the argument is a getter, it will be invoked and its return value will
  510. * be returned.
  511. *
  512. * @example
  513. * ```js
  514. * toValue(1) // 1
  515. * toValue(ref(1)) // 1
  516. * toValue(() => 1) // 1
  517. * ```
  518. *
  519. * @param source - A getter, an existing ref, or a non-function value.
  520. * @see {@link https://vuejs.org/api/reactivity-utilities.html#tovalue}
  521. */
  522. export declare function toValue<T>(source: MaybeRefOrGetter<T>): T;
  523. /**
  524. * Returns a proxy for the given object that shallowly unwraps properties that
  525. * are refs. If the object already is reactive, it's returned as-is. If not, a
  526. * new reactive proxy is created.
  527. *
  528. * @param objectWithRefs - Either an already-reactive object or a simple object
  529. * that contains refs.
  530. */
  531. export declare function proxyRefs<T extends object>(objectWithRefs: T): ShallowUnwrapRef<T>;
  532. export type CustomRefFactory<T, S = T> = (track: () => void, trigger: () => void) => {
  533. get: () => T;
  534. set: (value: S) => void;
  535. };
  536. /**
  537. * Creates a customized ref with explicit control over its dependency tracking
  538. * and updates triggering.
  539. *
  540. * @param factory - The function that receives the `track` and `trigger` callbacks.
  541. * @see {@link https://vuejs.org/api/reactivity-advanced.html#customref}
  542. */
  543. export declare function customRef<T, S = T>(factory: CustomRefFactory<T, S>): Ref<T, S>;
  544. export type ToRefs<T = any> = {
  545. [K in keyof T]: ToRef<T[K]>;
  546. };
  547. type ArrayStringKey<T> = T extends readonly any[] ? number extends T['length'] ? `${number}` : never : never;
  548. type ToRefKey<T> = keyof T | ArrayStringKey<T>;
  549. type ToRefValue<T extends object, K extends ToRefKey<T>> = K extends keyof T ? T[K] : T extends readonly (infer V)[] ? K extends ArrayStringKey<T> ? V : never : never;
  550. /**
  551. * Converts a reactive object to a plain object where each property of the
  552. * resulting object is a ref pointing to the corresponding property of the
  553. * original object. Each individual ref is created using {@link toRef}.
  554. *
  555. * @param object - Reactive object to be made into an object of linked refs.
  556. * @see {@link https://vuejs.org/api/reactivity-utilities.html#torefs}
  557. */
  558. export declare function toRefs<T extends object>(object: T): ToRefs<T>;
  559. export type ToRef<T> = IfAny<T, Ref<T>, [T] extends [Ref] ? T : Ref<T>>;
  560. /**
  561. * Used to normalize values / refs / getters into refs.
  562. *
  563. * @example
  564. * ```js
  565. * // returns existing refs as-is
  566. * toRef(existingRef)
  567. *
  568. * // creates a ref that calls the getter on .value access
  569. * toRef(() => props.foo)
  570. *
  571. * // creates normal refs from non-function values
  572. * // equivalent to ref(1)
  573. * toRef(1)
  574. * ```
  575. *
  576. * Can also be used to create a ref for a property on a source reactive object.
  577. * The created ref is synced with its source property: mutating the source
  578. * property will update the ref, and vice-versa.
  579. *
  580. * @example
  581. * ```js
  582. * const state = reactive({
  583. * foo: 1,
  584. * bar: 2
  585. * })
  586. *
  587. * const fooRef = toRef(state, 'foo')
  588. *
  589. * // mutating the ref updates the original
  590. * fooRef.value++
  591. * console.log(state.foo) // 2
  592. *
  593. * // mutating the original also updates the ref
  594. * state.foo++
  595. * console.log(fooRef.value) // 3
  596. * ```
  597. *
  598. * @param source - A getter, an existing ref, a non-function value, or a
  599. * reactive object to create a property ref from.
  600. * @param [key] - (optional) Name of the property in the reactive object.
  601. * @see {@link https://vuejs.org/api/reactivity-utilities.html#toref}
  602. */
  603. export declare function toRef<T>(value: T): T extends () => infer R ? Readonly<Ref<R>> : T extends Ref ? T : Ref<UnwrapRef<T>>;
  604. export declare function toRef<T extends object, K extends ToRefKey<T>>(object: T, key: K): ToRef<ToRefValue<T, K>>;
  605. export declare function toRef<T extends object, K extends ToRefKey<T>>(object: T, key: K, defaultValue: ToRefValue<T, K>): ToRef<Exclude<ToRefValue<T, K>, undefined>>;
  606. /**
  607. * This is a special exported interface for other packages to declare
  608. * additional types that should bail out for ref unwrapping. For example
  609. * \@vue/runtime-dom can declare it like so in its d.ts:
  610. *
  611. * ``` ts
  612. * declare module '@vue/reactivity' {
  613. * export interface RefUnwrapBailTypes {
  614. * runtimeDOMBailTypes: Node | Window
  615. * }
  616. * }
  617. * ```
  618. */
  619. export interface RefUnwrapBailTypes {
  620. }
  621. export type ShallowUnwrapRef<T> = T extends ShallowReactiveBrand ? T : {
  622. [K in keyof T]: DistributeRef<T[K]>;
  623. };
  624. type DistributeRef<T> = T extends Ref<infer V, unknown> ? V : T;
  625. export type UnwrapRef<T> = T extends ShallowRef<infer V, unknown> ? V : T extends Ref<infer V, unknown> ? UnwrapRefSimple<V> : UnwrapRefSimple<T>;
  626. type UnwrapRefSimple<T> = T extends Builtin | Ref | RefUnwrapBailTypes[keyof RefUnwrapBailTypes] | {
  627. [RawSymbol]?: true;
  628. } ? T : T extends ShallowReactiveBrand ? T : T extends Map<infer K, infer V> ? Map<K, UnwrapRefSimple<V>> & UnwrapRef<Omit<T, keyof Map<any, any>>> : T extends WeakMap<infer K, infer V> ? WeakMap<K, UnwrapRefSimple<V>> & UnwrapRef<Omit<T, keyof WeakMap<any, any>>> : T extends Set<infer V> ? Set<UnwrapRefSimple<V>> & UnwrapRef<Omit<T, keyof Set<any>>> : T extends WeakSet<infer V> ? WeakSet<UnwrapRefSimple<V>> & UnwrapRef<Omit<T, keyof WeakSet<any>>> : T extends ReadonlyArray<any> ? {
  629. [K in keyof T]: UnwrapRefSimple<T[K]>;
  630. } : T extends object ? {
  631. [P in keyof T]: P extends symbol ? T[P] : UnwrapRef<T[P]>;
  632. } : T;
  633. export declare const ITERATE_KEY: unique symbol;
  634. export declare const MAP_KEY_ITERATE_KEY: unique symbol;
  635. export declare const ARRAY_ITERATE_KEY: unique symbol;
  636. /**
  637. * Tracks access to a reactive property.
  638. *
  639. * This will check which effect is running at the moment and record it as dep
  640. * which records all effects that depend on the reactive property.
  641. *
  642. * @param target - Object holding the reactive property.
  643. * @param type - Defines the type of access to the reactive property.
  644. * @param key - Identifier of the reactive property to track.
  645. */
  646. export declare function track(target: object, type: TrackOpTypes, key: unknown): void;
  647. /**
  648. * Finds all deps associated with the target (or a specific property) and
  649. * triggers the effects stored within.
  650. *
  651. * @param target - The reactive object.
  652. * @param type - Defines the type of the operation that needs to trigger effects.
  653. * @param key - Can be used to target a specific reactive property in the target object.
  654. */
  655. export declare function trigger(target: object, type: TriggerOpTypes, key?: unknown, newValue?: unknown, oldValue?: unknown, oldTarget?: Map<unknown, unknown> | Set<unknown>): void;
  656. export declare class EffectScope {
  657. detached: boolean;
  658. private _isPaused;
  659. readonly __v_skip = true;
  660. constructor(detached?: boolean);
  661. get active(): boolean;
  662. pause(): void;
  663. /**
  664. * Resumes the effect scope, including all child scopes and effects.
  665. */
  666. resume(): void;
  667. run<T>(fn: () => T): T | undefined;
  668. prevScope: EffectScope | undefined;
  669. stop(fromParent?: boolean): void;
  670. }
  671. /**
  672. * Creates an effect scope object which can capture the reactive effects (i.e.
  673. * computed and watchers) created within it so that these effects can be
  674. * disposed together. For detailed use cases of this API, please consult its
  675. * corresponding {@link https://github.com/vuejs/rfcs/blob/master/active-rfcs/0041-reactivity-effect-scope.md | RFC}.
  676. *
  677. * @param detached - Can be used to create a "detached" effect scope.
  678. * @see {@link https://vuejs.org/api/reactivity-advanced.html#effectscope}
  679. */
  680. export declare function effectScope(detached?: boolean): EffectScope;
  681. /**
  682. * Returns the current active effect scope if there is one.
  683. *
  684. * @see {@link https://vuejs.org/api/reactivity-advanced.html#getcurrentscope}
  685. */
  686. export declare function getCurrentScope(): EffectScope | undefined;
  687. /**
  688. * Registers a dispose callback on the current active effect scope. The
  689. * callback will be invoked when the associated effect scope is stopped.
  690. *
  691. * @param fn - The callback function to attach to the scope's cleanup.
  692. * @see {@link https://vuejs.org/api/reactivity-advanced.html#onscopedispose}
  693. */
  694. export declare function onScopeDispose(fn: () => void, failSilently?: boolean): void;
  695. /**
  696. * Track array iteration and return:
  697. * - if input is reactive: a cloned raw array with reactive values
  698. * - if input is non-reactive or shallowReactive: the original raw array
  699. */
  700. export declare function reactiveReadArray<T>(array: T[]): T[];
  701. /**
  702. * Track array iteration and return raw array
  703. */
  704. export declare function shallowReadArray<T>(arr: T[]): T[];
  705. export declare enum WatchErrorCodes {
  706. WATCH_GETTER = 2,
  707. WATCH_CALLBACK = 3,
  708. WATCH_CLEANUP = 4
  709. }
  710. export type WatchEffect = (onCleanup: OnCleanup) => void;
  711. export type WatchSource<T = any> = Ref<T, any> | ComputedRef<T> | (() => T);
  712. export type WatchCallback<V = any, OV = any> = (value: V, oldValue: OV, onCleanup: OnCleanup) => any;
  713. export type OnCleanup = (cleanupFn: () => void) => void;
  714. export interface WatchOptions<Immediate = boolean> extends DebuggerOptions {
  715. immediate?: Immediate;
  716. deep?: boolean | number;
  717. once?: boolean;
  718. scheduler?: WatchScheduler;
  719. onWarn?: (msg: string, ...args: any[]) => void;
  720. }
  721. export type WatchStopHandle = () => void;
  722. export interface WatchHandle extends WatchStopHandle {
  723. pause: () => void;
  724. resume: () => void;
  725. stop: () => void;
  726. }
  727. export type WatchScheduler = (job: () => void, isFirstRun: boolean) => void;
  728. /**
  729. * Returns the current active effect if there is one.
  730. */
  731. export declare function getCurrentWatcher(): ReactiveEffect<any> | undefined;
  732. /**
  733. * Registers a cleanup callback on the current active effect. This
  734. * registered cleanup callback will be invoked right before the
  735. * associated effect re-runs.
  736. *
  737. * @param cleanupFn - The callback function to attach to the effect's cleanup.
  738. * @param failSilently - if `true`, will not throw warning when called without
  739. * an active effect.
  740. * @param owner - The effect that this cleanup function should be attached to.
  741. * By default, the current active effect.
  742. */
  743. export declare function onWatcherCleanup(cleanupFn: () => void, failSilently?: boolean, owner?: ReactiveEffect | undefined): void;
  744. export declare function watch(source: WatchSource | WatchSource[] | WatchEffect | object, cb?: WatchCallback | null, options?: WatchOptions): WatchHandle;
  745. export declare function traverse(value: unknown, depth?: number, seen?: Map<unknown, number>): unknown;