or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

computed.mdeffect-scopes.mdeffects.mdindex.mdreactive-objects.mdrefs.mdutilities.mdwatchers.md
tile.json

tessl/npm-vue--reactivity

Vue.js's standalone reactivity system providing reactive references, objects, computed values, effects, and watchers with fine-grained dependency tracking.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@vue/reactivity@3.5.x

To install, run

npx @tessl/cli install tessl/npm-vue--reactivity@3.5.0

index.mddocs/

Vue Reactivity

Vue Reactivity is a standalone reactive state management system that enables fine-grained reactive programming through proxies and dependency tracking. It provides reactive references, reactive objects, computed values, effects, and watchers that automatically track dependencies and trigger updates when state changes.

Package Information

  • Package Name: @vue/reactivity
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @vue/reactivity

Core Imports

import { 
  ref, reactive, computed, effect, watch,
  isRef, isReactive, toRaw, unref 
} from "@vue/reactivity";

For CommonJS:

const { 
  ref, reactive, computed, effect, watch,
  isRef, isReactive, toRaw, unref 
} = require("@vue/reactivity");

Basic Usage

import { ref, reactive, computed, effect, watch } from "@vue/reactivity";

// Create reactive references
const count = ref(0);
const name = ref("Vue");

// Create reactive objects
const state = reactive({
  items: [],
  loading: false
});

// Create computed values
const doubleCount = computed(() => count.value * 2);

// Run side effects
effect(() => {
  console.log(`Count is: ${count.value}`);
});

// Watch for changes
watch(count, (newValue, oldValue) => {
  console.log(`Count changed from ${oldValue} to ${newValue}`);
});

// Modify reactive data
count.value = 5; // Triggers effect and watcher
state.loading = true; // Reactive update

Architecture

Vue Reactivity is built around several key components:

  • Reactive References: Wrappers around primitive values that track access and mutations (ref, shallowRef)
  • Reactive Objects: Proxy-based reactive objects that track property access and changes (reactive, readonly)
  • Dependency Tracking: Automatic dependency collection and effect triggering system (track, trigger)
  • Computed Values: Cached derived values that update when dependencies change (computed)
  • Effects System: Side effect functions that re-run when dependencies change (effect, ReactiveEffect)
  • Watchers: Observation system for reactive data changes with callbacks (watch)
  • Effect Scopes: Grouping and cleanup management for effects (effectScope)

Capabilities

Reactive References

Core reactive reference system for wrapping primitive values and providing fine-grained reactivity tracking.

function ref<T>(value: T): Ref<UnwrapRef<T>, UnwrapRef<T> | T>;
function shallowRef<T>(value: T): ShallowRef<T>;
function isRef<T>(r: Ref<T> | unknown): r is Ref<T>;
function unref<T>(ref: MaybeRef<T> | ComputedRef<T>): T;
function triggerRef(ref: Ref): void;

interface Ref<T = any, S = T> {
  get value(): T;
  set value(_: S);
}

Reactive References

Reactive Objects

Proxy-based reactive objects that provide deep reactivity tracking for complex data structures.

function reactive<T extends object>(target: T): Reactive<T>;
function readonly<T extends object>(target: T): DeepReadonly<UnwrapNestedRefs<T>>;
function shallowReactive<T extends object>(target: T): ShallowReactive<T>;
function shallowReadonly<T extends object>(target: T): Readonly<T>;
function isReactive(value: unknown): boolean;
function isReadonly(value: unknown): boolean;
function toRaw<T>(observed: T): T;

Reactive Objects

Computed Values

Cached derived values that automatically update when their dependencies change, with support for both readonly and writable computed properties.

function computed<T>(getter: ComputedGetter<T>): ComputedRef<T>;
function computed<T, S = T>(options: WritableComputedOptions<T, S>): WritableComputedRef<T, S>;

interface ComputedRef<T = any> {
  readonly value: T;
}

type ComputedGetter<T> = (oldValue?: T) => T;

Computed Values

Effects System

Reactive effect system that automatically tracks dependencies and re-runs functions when reactive data changes.

function effect<T = any>(fn: () => T, options?: ReactiveEffectOptions): ReactiveEffectRunner<T>;
function stop(runner: ReactiveEffectRunner): void;
function onEffectCleanup(fn: () => void): void;

class ReactiveEffect<T = any> {
  constructor(public fn: () => T);
  run(): T;
  stop(): void;
  trigger(): void;
}

Effects System

Watchers

Advanced observation system for reactive data changes with customizable callbacks, immediate execution, and deep watching options.

function watch<T>(
  source: WatchSource<T> | WatchSource<T>[],
  cb: WatchCallback<T>,
  options?: WatchOptions
): WatchHandle;

interface WatchHandle {
  pause: () => void;
  resume: () => void;
  stop: () => void;
}

type WatchCallback<V = any, OV = any> = (
  value: V,
  oldValue: OV,
  onCleanup: (fn: () => void) => void
) => any;

Watchers

Effect Scopes

Grouping and cleanup management system for organizing and disposing of effects in a controlled manner.

function effectScope(detached?: boolean): EffectScope;
function getCurrentScope(): EffectScope | undefined;
function onScopeDispose(fn: () => void): void;

class EffectScope {
  get active(): boolean;
  run<T>(fn: () => T): T | undefined;
  stop(): void;
  pause(): void;
  resume(): void;
}

Effect Scopes

Low-level Dependency Tracking

Low-level functions for manual dependency tracking and triggering. These are typically used internally but are available for advanced use cases.

function track(target: object, type: TrackOpTypes, key: unknown): void;
function trigger(
  target: object,
  type: TriggerOpTypes,
  key?: unknown,
  newValue?: unknown,
  oldValue?: unknown,
  oldTarget?: Map<unknown, unknown> | Set<unknown>
): void;

// Iteration tracking keys
const ITERATE_KEY: unique symbol;
const ARRAY_ITERATE_KEY: unique symbol;
const MAP_KEY_ITERATE_KEY: unique symbol;

Array Instrumentations

Functions for handling reactive array reading with proper dependency tracking.

function reactiveReadArray<T>(array: T[]): T[];
function shallowReadArray<T>(arr: T[]): T[];

Tracking Control

Functions for manually controlling dependency tracking state during effect execution.

function enableTracking(): void;
function pauseTracking(): void;
function resetTracking(): void;

Utility Functions

Utility functions for converting between reactive and non-reactive values, type checking, and advanced reactive operations.

function toRef<T>(value: T): ToRef<T>;
function toRefs<T extends object>(object: T): ToRefs<T>;
function toValue<T>(source: MaybeRefOrGetter<T>): T;
function markRaw<T extends object>(value: T): Raw<T>;
function customRef<T>(factory: CustomRefFactory<T>): Ref<T>;
function proxyRefs<T extends object>(objectWithRefs: T): ShallowUnwrapRef<T>;
function isProxy(value: any): boolean;
function isShallow(value: unknown): boolean;
function toReactive<T>(value: T): T;
function toReadonly<T>(value: T): T;

Utility Functions

Types

// Core reference types
type MaybeRef<T = any> = T | Ref<T> | ShallowRef<T> | WritableComputedRef<T>;
type MaybeRefOrGetter<T = any> = MaybeRef<T> | ComputedRef<T> | (() => T);
type UnwrapRef<T> = T extends ShallowRef<infer V> ? V : T extends Ref<infer V> ? UnwrapRefSimple<V> : UnwrapRefSimple<T>;
type ShallowUnwrapRef<T> = { [K in keyof T]: DistributeRef<T[K]> };
type UnwrapNestedRefs<T> = T extends Ref ? T : UnwrapRefSimple<T>;

// Reactive object types
type Reactive<T> = UnwrapNestedRefs<T>;
type DeepReadonly<T> = { readonly [P in keyof T]: DeepReadonly<T[P]> };
type ShallowReactive<T> = T;
type Raw<T> = T & { [RawSymbol]?: true };

// Utility types
type ToRef<T> = [T] extends [Ref] ? T : Ref<T>;
type ToRefs<T = any> = { [K in keyof T]: ToRef<T[K]> };

// Effect and watch types
type ReactiveEffectRunner<T = any> = (() => T) & { effect: ReactiveEffect };
type WatchSource<T = any> = Ref<T, any> | ComputedRef<T> | (() => T);
type CustomRefFactory<T> = (track: () => void, trigger: () => void) => { get: () => T; set: (value: T) => void };

// Options types
interface ReactiveEffectOptions {
  scheduler?: EffectScheduler;
  allowRecurse?: boolean;
  onStop?: () => void;
}

interface WritableComputedOptions<T, S = T> {
  get: ComputedGetter<T>;
  set: ComputedSetter<S>;
}

Constants and Enums

enum TrackOpTypes {
  GET = 'get',
  HAS = 'has',
  ITERATE = 'iterate'
}

enum TriggerOpTypes {
  SET = 'set',
  ADD = 'add',
  DELETE = 'delete',
  CLEAR = 'clear'
}

enum ReactiveFlags {
  SKIP = '__v_skip',
  IS_REACTIVE = '__v_isReactive',
  IS_READONLY = '__v_isReadonly',
  IS_SHALLOW = '__v_isShallow',
  RAW = '__v_raw',
  IS_REF = '__v_isRef'
}

enum EffectFlags {
  ACTIVE = 1,
  RUNNING = 2,
  TRACKING = 4,
  NOTIFIED = 8,
  DIRTY = 16,
  ALLOW_RECURSE = 32,
  PAUSED = 64,
  EVALUATED = 128
}