@ng-org/alien-deepsignals 0.1.2

package/dist/index.d.mts

@@ -0,0 +1,238 @@
+import { signal as signal$1, computed as computed$1 } from 'alien-signals';
+export { computed as _rawComputed, effect as _rawEffect, endBatch as _rawEndBatch, getCurrentSub as _rawGetCurrentSub, setCurrentSub as _rawSetCurrentSub, signal as _rawSignal, startBatch as _rawStartBatch } from 'alien-signals';
+
+/** Lightweight facade adding ergonomic helpers (.value/.peek/.get/.set) to native alien-signals function signals. */
+
+/** Internal shape of a tagged writable signal after adding ergonomic helpers. */
+type TaggedSignal<T> = ReturnType<typeof signal$1<T>> & {
+    /** Tracking read / write via property syntax */
+    value: T;
+    /** Non-tracking read */
+    peek(): T;
+    /** Alias for tracking read */
+    get(): T;
+    /** Write helper */
+    set(v: T): void;
+};
+/**
+ * Create a new writable function-form signal enhanced with `.value`, `.peek()`, `.get()`, `.set()`.
+ *
+ * @example
+ * const count = signal(0);
+ * count();      // 0 (track)
+ * count(1);     // write
+ * count.value;  // 1 (track)
+ * count.peek(); // 1 (non-tracking)
+ */
+declare const signal: <T>(v?: T) => TaggedSignal<any>;
+/** Internal shape of a tagged computed signal after adding ergonomic helpers. */
+type TaggedComputed<T> = ReturnType<typeof computed$1<T>> & {
+    /** Tracking read via property syntax (readonly) */
+    readonly value: T;
+    /** Non-tracking read */
+    peek(): T;
+    /** Alias for tracking read */
+    get(): T;
+};
+/**
+ * Create a lazy computed (readonly) signal derived from other signals.
+ *
+ * Computed signals are automatically cached and only recompute when their tracked
+ * dependencies change. The getter function is evaluated lazily—if you never read
+ * the computed value, the computation never runs.
+ *
+ * The returned function can be called directly `computed()` or accessed via `.value`.
+ * Use `.peek()` for non-tracking reads (won't establish reactive dependency).
+ *
+ * @example
+ * const count = signal(5);
+ * const doubled = computed(() => count() * 2);
+ * doubled();       // 10 (establishes dependency, caches result)
+ * doubled.value;   // 10 (cached, same as calling it)
+ * doubled.peek();  // 10 (no dependency tracking)
+ * count(10);
+ * doubled();       // 20 (recomputed because count changed)
+ */
+declare const computed: <T>(getter: () => T) => TaggedComputed<T>;
+/** Union allowing a plain value or a writable signal wrapping that value. */
+type MaybeSignal<T = any> = T | ReturnType<typeof signal>;
+/** Union allowing value, writable signal, computed signal or plain getter function. */
+type MaybeSignalOrGetter<T = any> = MaybeSignal<T> | ReturnType<typeof computed> | (() => T);
+/** Runtime guard that an unknown value is one of our tagged signals/computeds. */
+declare const isSignal: (s: any) => boolean;
+/**
+ * Execute multiple signal writes in a single batched update frame.
+ * All downstream computed/effect re-evaluations are deferred until the function exits.
+ *
+ * IMPORTANT: The callback MUST be synchronous. If it returns a Promise the batch will
+ * still end immediately after scheduling, possibly causing mid-async flushes.
+ *
+ * @example
+ * batch(() => {
+ *   count(count() + 1);
+ *   other(other() + 2);
+ * }); // effects observing both run only once
+ */
+declare function batch<T>(fn: () => T): T;
+
+/** Deep mutation emitted from a deepSignal root. */
+type DeepPatch = {
+    path: (string | number)[];
+} & ({
+    op: "add";
+    type?: "object" | "set";
+    value?: any;
+} | {
+    op: "remove";
+    type?: "set";
+    value?: any;
+});
+/** Batched patch payload tagged with a monotonically increasing version. */
+interface DeepPatchBatch {
+    version: number;
+    patches: DeepPatch[];
+}
+/** Batched patch payload for justInTime listeners. */
+interface DeepPatchJITBatch {
+    patches: DeepPatch[];
+}
+type DeepPatchSubscriber = (batch: DeepPatchBatch) => void;
+type DeepPatchJITSubscriber = (batch: DeepPatchJITBatch) => void;
+interface DeepSignalOptions {
+    propGenerator?: DeepSignalPropGenFn;
+    syntheticIdPropertyName?: string;
+    readOnlyProps?: string[];
+}
+type DeepSignalPropGenFn = (props: {
+    path: (string | number)[];
+    inSet: boolean;
+    object: any;
+}) => {
+    syntheticId?: string | number;
+    extraProps?: Record<string, unknown>;
+};
+interface ProxyMeta {
+    raw: object;
+    parent?: object;
+    key?: string | number | symbol;
+    isSyntheticId?: boolean;
+    root: symbol;
+    options: DeepSignalOptions;
+    setInfo?: SetMeta;
+}
+interface SetMeta {
+    idForObject: WeakMap<object, string>;
+    objectForId: Map<string, object>;
+}
+interface RootState {
+    options?: DeepSignalOptions;
+    version: number;
+    justInTimeListeners: Set<DeepPatchJITSubscriber>;
+    listeners: Set<DeepPatchSubscriber>;
+    pendingPatches: DeepPatch[];
+}
+type WritableSignalFunction<T> = typeof signal<T>;
+type ComputedSignalFunction<T> = typeof computed<T>;
+type WritableSignal<T = any> = ReturnType<WritableSignalFunction<T>>;
+type ComputedSignal<T = any> = ReturnType<ComputedSignalFunction<T>>;
+type SignalLike<T = any> = WritableSignal<T> | ComputedSignal<T>;
+/** Raw and meta key. */
+type DeepSignalObjectProps<T> = {
+    __raw__: T;
+    __meta__: ProxyMeta;
+};
+/** Utility functions for sets. */
+type DeepSignalSetProps<T> = {
+    /** Get the element that was first inserted into the set. */
+    first(): undefined | (T extends object ? DeepSignal<T> : T);
+    /**
+     * Retrieve an entry from the Set by its synthetic ID.
+     * @param id - The synthetic ID (string or number) assigned to the entry.
+     * @returns The proxied entry if found, undefined otherwise.
+     */
+    getById(id: string | number): DeepSignal<T> | undefined;
+    /**
+     * Retrieve an entry from the Set by constructing an ID from graphIri and subjectIri.
+     * This is a convenience method that constructs the ID as "graphIri|subjectIri".
+     * @param graphIri - The graph IRI part of the identifier.
+     * @param subjectIri - The subject IRI part of the identifier.
+     * @returns The proxied entry if found, undefined otherwise.
+     */
+    getBy(graphIri: string, subjectIri: string): DeepSignal<T> | undefined;
+};
+/** Reactive Set wrapper that accepts raw or proxied entries. */
+interface DeepSignalSet<T> extends Set<DeepSignal<T>>, DeepSignalObjectProps<Set<T>>, SetIterator<DeepSignal<T>>, DeepSignalSetProps<T> {
+    add(value: T | DeepSignal<T>): this;
+    delete(value: T | DeepSignal<T>): boolean;
+    has(value: T | DeepSignal<T>): boolean;
+    forEach(callbackfn: (value: DeepSignal<T>, value2: DeepSignal<T>, set: DeepSignalSet<T>) => void, thisArg?: any): void;
+    forEach(callbackfn: (value: DeepSignal<T>, index: number) => void, thisArg?: any): void;
+}
+/**
+ * The object returned by the @see deepSignal function.
+ * It is decorated with utility functions for sets and a
+ * `__raw__` prop to get the underlying non-reactive object
+ * and `__meta__` prop, to get the internal metadata.
+ */
+type DeepSignal<T> = T extends Function ? T : T extends string | number | boolean ? T : T extends DeepSignalObjectProps<any> | DeepSignalObjectProps<any>[] ? T : T extends Array<infer I> ? DeepSignal<I>[] : T extends Set<infer S> ? DeepSignalSet<S> : T extends object ? DeepSignalObject<T> : T;
+type DeepSignalObject<T extends object> = {
+    [K in keyof T]: DeepSignal<T[K]>;
+};
+type RevertDeepSignal<T> = T extends DeepSignal<infer S> ? S : T;
+
+/** Runtime guard that checks whether a value is a deepSignal proxy. */
+declare function isDeepSignal(value: any): boolean;
+/**
+ * Create a deep reactive proxy for objects, arrays or Sets.
+ * Returns the input itself, if it's a deepSignal already.
+ * Throws if provided with unsupported input types.
+ */
+declare function deepSignal<T extends object>(input: T, options?: DeepSignalOptions): DeepSignal<T>;
+/**
+ * Low-level function, you should probably use `watch` instead.
+ *
+ * Register a deep mutation subscriber for the provided root or proxy.
+ */
+declare function subscribeDeepMutations(root: object | symbol, cb: DeepPatchSubscriber | DeepPatchJITSubscriber, triggerInstantly?: boolean): () => void;
+/** Return the root identifier symbol for a deepSignal proxy (if any). */
+declare function getDeepSignalRootId(value: any): symbol | undefined;
+/** Retrieve the current patch version for a deepSignal root (if tracked). */
+declare function getDeepSignalVersion(root: object | symbol): number | undefined;
+/** Mark an object so deepSignal skips proxying it (shallow boundary). */
+declare function shallow<T extends object>(obj: T): T;
+/** Force a specific synthetic ID to be used for a Set entry prior to insertion. */
+declare function setSetEntrySyntheticId(obj: object, id: string | number): void;
+/** Convenience helper to add an entry to a proxied Set with a pre-defined synthetic ID. */
+declare function addWithId<T>(set: Set<T>, entry: T, id: string | number): T;
+
+type RegisterCleanup$1 = (cleanupFn: () => void) => void;
+interface WatchOptions {
+    /** True, if the callback should be run immediately after `watch` was called. @default false*/
+    immediate?: boolean;
+    /** True, if the watcher should be unsubscribed after the first event. @default false*/
+    once?: boolean;
+    /**
+     * If true, triggers watch callback instantly after changes to the signal object.
+     * Otherwise, changes are batched and the watch callback is triggered in a microtask.
+     * This is useful for frontends like React where modifications on the changed input in
+     * a separate (microtask) will cause the cursor in input elements to reset.
+     */
+    triggerInstantly?: boolean;
+}
+interface WatchPatchEvent<T extends object> {
+    patches: DeepPatch[];
+    /** The version if `triggerInstantly` is not true. */
+    version?: number;
+    newValue: DeepSignal<T>;
+}
+type WatchPatchCallback<T extends object> = (event: WatchPatchEvent<T>) => void;
+declare function watch<T extends object>(source: DeepSignal<T>, callback: WatchPatchCallback<T>, options?: WatchOptions): {
+    stopListening: () => void;
+    registerCleanup: RegisterCleanup$1;
+};
+
+type RegisterCleanup = (cleanup: () => void) => void;
+/** Wrap `alien-signals` effect with optional cleanup registration. */
+declare function effect(run: (registerCleanup?: RegisterCleanup) => void): () => void;
+
+export { type ComputedSignal, type DeepPatch, type DeepPatchBatch, type DeepPatchJITBatch, type DeepPatchJITSubscriber, type DeepPatchSubscriber, type DeepSignal, type DeepSignalObject, type DeepSignalObjectProps, type DeepSignalOptions, type DeepSignalPropGenFn, type DeepSignalSet, type DeepSignalSetProps, type MaybeSignal, type MaybeSignalOrGetter, type ProxyMeta, type RegisterCleanup$1 as RegisterCleanup, type RevertDeepSignal, type RootState, type SetMeta, type SignalLike, type WatchOptions, type WatchPatchCallback, type WatchPatchEvent, type WritableSignal, addWithId, batch, computed, deepSignal, effect, getDeepSignalRootId, getDeepSignalVersion, isDeepSignal, isSignal, setSetEntrySyntheticId, shallow, signal, subscribeDeepMutations, watch };

package/dist/index.d.ts

@@ -0,0 +1,238 @@
+import { signal as signal$1, computed as computed$1 } from 'alien-signals';
+export { computed as _rawComputed, effect as _rawEffect, endBatch as _rawEndBatch, getCurrentSub as _rawGetCurrentSub, setCurrentSub as _rawSetCurrentSub, signal as _rawSignal, startBatch as _rawStartBatch } from 'alien-signals';
+
+/** Lightweight facade adding ergonomic helpers (.value/.peek/.get/.set) to native alien-signals function signals. */
+
+/** Internal shape of a tagged writable signal after adding ergonomic helpers. */
+type TaggedSignal<T> = ReturnType<typeof signal$1<T>> & {
+    /** Tracking read / write via property syntax */
+    value: T;
+    /** Non-tracking read */
+    peek(): T;
+    /** Alias for tracking read */
+    get(): T;
+    /** Write helper */
+    set(v: T): void;
+};
+/**
+ * Create a new writable function-form signal enhanced with `.value`, `.peek()`, `.get()`, `.set()`.
+ *
+ * @example
+ * const count = signal(0);
+ * count();      // 0 (track)
+ * count(1);     // write
+ * count.value;  // 1 (track)
+ * count.peek(); // 1 (non-tracking)
+ */
+declare const signal: <T>(v?: T) => TaggedSignal<any>;
+/** Internal shape of a tagged computed signal after adding ergonomic helpers. */
+type TaggedComputed<T> = ReturnType<typeof computed$1<T>> & {
+    /** Tracking read via property syntax (readonly) */
+    readonly value: T;
+    /** Non-tracking read */
+    peek(): T;
+    /** Alias for tracking read */
+    get(): T;
+};
+/**
+ * Create a lazy computed (readonly) signal derived from other signals.
+ *
+ * Computed signals are automatically cached and only recompute when their tracked
+ * dependencies change. The getter function is evaluated lazily—if you never read
+ * the computed value, the computation never runs.
+ *
+ * The returned function can be called directly `computed()` or accessed via `.value`.
+ * Use `.peek()` for non-tracking reads (won't establish reactive dependency).
+ *
+ * @example
+ * const count = signal(5);
+ * const doubled = computed(() => count() * 2);
+ * doubled();       // 10 (establishes dependency, caches result)
+ * doubled.value;   // 10 (cached, same as calling it)
+ * doubled.peek();  // 10 (no dependency tracking)
+ * count(10);
+ * doubled();       // 20 (recomputed because count changed)
+ */
+declare const computed: <T>(getter: () => T) => TaggedComputed<T>;
+/** Union allowing a plain value or a writable signal wrapping that value. */
+type MaybeSignal<T = any> = T | ReturnType<typeof signal>;
+/** Union allowing value, writable signal, computed signal or plain getter function. */
+type MaybeSignalOrGetter<T = any> = MaybeSignal<T> | ReturnType<typeof computed> | (() => T);
+/** Runtime guard that an unknown value is one of our tagged signals/computeds. */
+declare const isSignal: (s: any) => boolean;
+/**
+ * Execute multiple signal writes in a single batched update frame.
+ * All downstream computed/effect re-evaluations are deferred until the function exits.
+ *
+ * IMPORTANT: The callback MUST be synchronous. If it returns a Promise the batch will
+ * still end immediately after scheduling, possibly causing mid-async flushes.
+ *
+ * @example
+ * batch(() => {
+ *   count(count() + 1);
+ *   other(other() + 2);
+ * }); // effects observing both run only once
+ */
+declare function batch<T>(fn: () => T): T;
+
+/** Deep mutation emitted from a deepSignal root. */
+type DeepPatch = {
+    path: (string | number)[];
+} & ({
+    op: "add";
+    type?: "object" | "set";
+    value?: any;
+} | {
+    op: "remove";
+    type?: "set";
+    value?: any;
+});
+/** Batched patch payload tagged with a monotonically increasing version. */
+interface DeepPatchBatch {
+    version: number;
+    patches: DeepPatch[];
+}
+/** Batched patch payload for justInTime listeners. */
+interface DeepPatchJITBatch {
+    patches: DeepPatch[];
+}
+type DeepPatchSubscriber = (batch: DeepPatchBatch) => void;
+type DeepPatchJITSubscriber = (batch: DeepPatchJITBatch) => void;
+interface DeepSignalOptions {
+    propGenerator?: DeepSignalPropGenFn;
+    syntheticIdPropertyName?: string;
+    readOnlyProps?: string[];
+}
+type DeepSignalPropGenFn = (props: {
+    path: (string | number)[];
+    inSet: boolean;
+    object: any;
+}) => {
+    syntheticId?: string | number;
+    extraProps?: Record<string, unknown>;
+};
+interface ProxyMeta {
+    raw: object;
+    parent?: object;
+    key?: string | number | symbol;
+    isSyntheticId?: boolean;
+    root: symbol;
+    options: DeepSignalOptions;
+    setInfo?: SetMeta;
+}
+interface SetMeta {
+    idForObject: WeakMap<object, string>;
+    objectForId: Map<string, object>;
+}
+interface RootState {
+    options?: DeepSignalOptions;
+    version: number;
+    justInTimeListeners: Set<DeepPatchJITSubscriber>;
+    listeners: Set<DeepPatchSubscriber>;
+    pendingPatches: DeepPatch[];
+}
+type WritableSignalFunction<T> = typeof signal<T>;
+type ComputedSignalFunction<T> = typeof computed<T>;
+type WritableSignal<T = any> = ReturnType<WritableSignalFunction<T>>;
+type ComputedSignal<T = any> = ReturnType<ComputedSignalFunction<T>>;
+type SignalLike<T = any> = WritableSignal<T> | ComputedSignal<T>;
+/** Raw and meta key. */
+type DeepSignalObjectProps<T> = {
+    __raw__: T;
+    __meta__: ProxyMeta;
+};
+/** Utility functions for sets. */
+type DeepSignalSetProps<T> = {
+    /** Get the element that was first inserted into the set. */
+    first(): undefined | (T extends object ? DeepSignal<T> : T);
+    /**
+     * Retrieve an entry from the Set by its synthetic ID.
+     * @param id - The synthetic ID (string or number) assigned to the entry.
+     * @returns The proxied entry if found, undefined otherwise.
+     */
+    getById(id: string | number): DeepSignal<T> | undefined;
+    /**
+     * Retrieve an entry from the Set by constructing an ID from graphIri and subjectIri.
+     * This is a convenience method that constructs the ID as "graphIri|subjectIri".
+     * @param graphIri - The graph IRI part of the identifier.
+     * @param subjectIri - The subject IRI part of the identifier.
+     * @returns The proxied entry if found, undefined otherwise.
+     */
+    getBy(graphIri: string, subjectIri: string): DeepSignal<T> | undefined;
+};
+/** Reactive Set wrapper that accepts raw or proxied entries. */
+interface DeepSignalSet<T> extends Set<DeepSignal<T>>, DeepSignalObjectProps<Set<T>>, SetIterator<DeepSignal<T>>, DeepSignalSetProps<T> {
+    add(value: T | DeepSignal<T>): this;
+    delete(value: T | DeepSignal<T>): boolean;
+    has(value: T | DeepSignal<T>): boolean;
+    forEach(callbackfn: (value: DeepSignal<T>, value2: DeepSignal<T>, set: DeepSignalSet<T>) => void, thisArg?: any): void;
+    forEach(callbackfn: (value: DeepSignal<T>, index: number) => void, thisArg?: any): void;
+}
+/**
+ * The object returned by the @see deepSignal function.
+ * It is decorated with utility functions for sets and a
+ * `__raw__` prop to get the underlying non-reactive object
+ * and `__meta__` prop, to get the internal metadata.
+ */
+type DeepSignal<T> = T extends Function ? T : T extends string | number | boolean ? T : T extends DeepSignalObjectProps<any> | DeepSignalObjectProps<any>[] ? T : T extends Array<infer I> ? DeepSignal<I>[] : T extends Set<infer S> ? DeepSignalSet<S> : T extends object ? DeepSignalObject<T> : T;
+type DeepSignalObject<T extends object> = {
+    [K in keyof T]: DeepSignal<T[K]>;
+};
+type RevertDeepSignal<T> = T extends DeepSignal<infer S> ? S : T;
+
+/** Runtime guard that checks whether a value is a deepSignal proxy. */
+declare function isDeepSignal(value: any): boolean;
+/**
+ * Create a deep reactive proxy for objects, arrays or Sets.
+ * Returns the input itself, if it's a deepSignal already.
+ * Throws if provided with unsupported input types.
+ */
+declare function deepSignal<T extends object>(input: T, options?: DeepSignalOptions): DeepSignal<T>;
+/**
+ * Low-level function, you should probably use `watch` instead.
+ *
+ * Register a deep mutation subscriber for the provided root or proxy.
+ */
+declare function subscribeDeepMutations(root: object | symbol, cb: DeepPatchSubscriber | DeepPatchJITSubscriber, triggerInstantly?: boolean): () => void;
+/** Return the root identifier symbol for a deepSignal proxy (if any). */
+declare function getDeepSignalRootId(value: any): symbol | undefined;
+/** Retrieve the current patch version for a deepSignal root (if tracked). */
+declare function getDeepSignalVersion(root: object | symbol): number | undefined;
+/** Mark an object so deepSignal skips proxying it (shallow boundary). */
+declare function shallow<T extends object>(obj: T): T;
+/** Force a specific synthetic ID to be used for a Set entry prior to insertion. */
+declare function setSetEntrySyntheticId(obj: object, id: string | number): void;
+/** Convenience helper to add an entry to a proxied Set with a pre-defined synthetic ID. */
+declare function addWithId<T>(set: Set<T>, entry: T, id: string | number): T;
+
+type RegisterCleanup$1 = (cleanupFn: () => void) => void;
+interface WatchOptions {
+    /** True, if the callback should be run immediately after `watch` was called. @default false*/
+    immediate?: boolean;
+    /** True, if the watcher should be unsubscribed after the first event. @default false*/
+    once?: boolean;
+    /**
+     * If true, triggers watch callback instantly after changes to the signal object.
+     * Otherwise, changes are batched and the watch callback is triggered in a microtask.
+     * This is useful for frontends like React where modifications on the changed input in
+     * a separate (microtask) will cause the cursor in input elements to reset.
+     */
+    triggerInstantly?: boolean;
+}
+interface WatchPatchEvent<T extends object> {
+    patches: DeepPatch[];
+    /** The version if `triggerInstantly` is not true. */
+    version?: number;
+    newValue: DeepSignal<T>;
+}
+type WatchPatchCallback<T extends object> = (event: WatchPatchEvent<T>) => void;
+declare function watch<T extends object>(source: DeepSignal<T>, callback: WatchPatchCallback<T>, options?: WatchOptions): {
+    stopListening: () => void;
+    registerCleanup: RegisterCleanup$1;
+};
+
+type RegisterCleanup = (cleanup: () => void) => void;
+/** Wrap `alien-signals` effect with optional cleanup registration. */
+declare function effect(run: (registerCleanup?: RegisterCleanup) => void): () => void;
+
+export { type ComputedSignal, type DeepPatch, type DeepPatchBatch, type DeepPatchJITBatch, type DeepPatchJITSubscriber, type DeepPatchSubscriber, type DeepSignal, type DeepSignalObject, type DeepSignalObjectProps, type DeepSignalOptions, type DeepSignalPropGenFn, type DeepSignalSet, type DeepSignalSetProps, type MaybeSignal, type MaybeSignalOrGetter, type ProxyMeta, type RegisterCleanup$1 as RegisterCleanup, type RevertDeepSignal, type RootState, type SetMeta, type SignalLike, type WatchOptions, type WatchPatchCallback, type WatchPatchEvent, type WritableSignal, addWithId, batch, computed, deepSignal, effect, getDeepSignalRootId, getDeepSignalVersion, isDeepSignal, isSignal, setSetEntrySyntheticId, shallow, signal, subscribeDeepMutations, watch };