@ng-org/alien-deepsignals 0.1.2-alpha.5 → 0.1.2-alpha.7

package/dist/core.js

@@ -9,105 +9,93 @@
 // according to those terms.
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isSignal = exports.computed = exports.signal = exports._rawEffect = exports._rawSetCurrentSub = exports._rawGetCurrentSub = exports._rawEndBatch = exports._rawStartBatch = exports._rawComputed = exports._rawSignal = void 0;
+exports.effect = exports.alienSignal = exports.computed = void 0;
 exports.batch = batch;
-/** Lightweight facade adding ergonomic helpers (.value/.peek/.get/.set) to native alien-signals function signals. */
-// Native re-exports for advanced usage.
-var alien_signals_1 = require("alien-signals");
-Object.defineProperty(exports, "_rawSignal", { enumerable: true, get: function () { return alien_signals_1.signal; } });
-Object.defineProperty(exports, "_rawComputed", { enumerable: true, get: function () { return alien_signals_1.computed; } });
-Object.defineProperty(exports, "_rawStartBatch", { enumerable: true, get: function () { return alien_signals_1.startBatch; } });
-Object.defineProperty(exports, "_rawEndBatch", { enumerable: true, get: function () { return alien_signals_1.endBatch; } });
-Object.defineProperty(exports, "_rawGetCurrentSub", { enumerable: true, get: function () { return alien_signals_1.getCurrentSub; } });
-Object.defineProperty(exports, "_rawSetCurrentSub", { enumerable: true, get: function () { return alien_signals_1.setCurrentSub; } });
-Object.defineProperty(exports, "_rawEffect", { enumerable: true, get: function () { return alien_signals_1.effect; } });
-const alien_signals_2 = require("alien-signals");
-const contents_1 = require("./contents");
-/**
- * Decorate a native signal function with helpers & identity.
- */
-function tagSignal(fn) {
-    Object.defineProperty(fn, contents_1.ReactiveFlags.IS_SIGNAL, { value: true });
-    Object.defineProperty(fn, "value", {
-        get: () => fn(),
-        set: (v) => fn(v),
-    });
-    // Add peek to mirror old API (non-tracking read)
-    if (!fn.peek)
-        Object.defineProperty(fn, "peek", { value: () => fn() });
-    if (!fn.get)
-        Object.defineProperty(fn, "get", { value: () => fn() });
-    if (!fn.set)
-        Object.defineProperty(fn, "set", { value: (v) => fn(v) });
-    return fn;
-}
-/**
- * Decorate a native computed function with ergonomic helpers & readonly value accessor.
- */
-function tagComputed(fn) {
-    Object.defineProperty(fn, contents_1.ReactiveFlags.IS_SIGNAL, { value: true });
-    Object.defineProperty(fn, "value", { get: () => fn() });
-    if (!fn.peek)
-        Object.defineProperty(fn, "peek", { value: () => fn() });
-    if (!fn.get)
-        Object.defineProperty(fn, "get", { value: () => fn() });
-    return fn;
-}
-/**
- * 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)
- */
-const signal = (v) => tagSignal((0, alien_signals_2.signal)(v));
-exports.signal = signal;
-/**
- * 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)
- */
-const computed = (getter) => tagComputed((0, alien_signals_2.computed)(getter));
-exports.computed = computed;
-/** Runtime guard that an unknown value is one of our tagged signals/computeds. */
-const isSignal = (s) => typeof s === "function" && !!s && !!s[contents_1.ReactiveFlags.IS_SIGNAL];
-exports.isSignal = isSignal;
+const alien_signals_1 = require("alien-signals");
 /**
  * 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
+ * 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
+ * ```ts
  * batch(() => {
  *   count(count() + 1);
  *   other(other() + 2);
  * }); // effects observing both run only once
+ * ```
  */
 function batch(fn) {
-    (0, alien_signals_2.startBatch)();
+    (0, alien_signals_1.startBatch)();
     try {
         return fn();
     }
     finally {
-        (0, alien_signals_2.endBatch)();
+        (0, alien_signals_1.endBatch)();
     }
 }
+/**
+ * Re-export of alien-signals computed function.
+ *
+ * Use the `computed()` function to create lazy derived signals that automatically
+ * track their dependencies and recompute only when needed.
+ *
+ * Key features:
+ * - **Lazy evaluation**: The computation runs only when you actually read the computed value.
+ *     If you never access `fullName()`, the concatenation never happens—no wasted CPU cycles.
+ * - **Automatic caching**: Once computed, the result is cached until a dependency changes.
+ *     Multiple reads return the cached value without re-running the getter.
+ * - **Fine-grained reactivity**: Only recomputes when its tracked dependencies change.
+ *     Unrelated state mutations don't trigger unnecessary recalculation.
+ * - **Composable**: Computed signals can depend on other computed signals,
+ *     forming efficient dependency chains.
+ *
+ * @example
+ * ```ts
+ * import { computed } from "@ng-org/alien-deepsignals";
+ *
+ * const state = deepSignal({
+ *     firstName: "Ada",
+ *     lastName: "Lovelace",
+ *     items: [1, 2, 3],
+ * });
+ *
+ * // Create a computed signal that derives from reactive state
+ * const fullName = computed(() => `${state.firstName} ${state.lastName}`);
+ *
+ * console.log(fullName()); // "Ada Lovelace" - computes on first access
+ *
+ * state.firstName = "Grace";
+ * console.log(fullName()); // "Grace Lovelace" - recomputes automatically
+ *
+ * // Expensive computation only runs when accessed and dependencies change
+ * const expensiveResult = computed(() => {
+ *     console.log("Computing...");
+ *     return state.items.reduce((sum, n) => sum + n * n, 0);
+ * });
+ *
+ * // No computation happens yet!
+ * state.items.push(4);
+ * // Still no computation...
+ *
+ * console.log(expensiveResult()); // "Computing..." + result
+ * console.log(expensiveResult()); // Cached, no log
+ * state.items.push(5);
+ * console.log(expensiveResult()); // "Computing..." again (dependency changed)
+ *
+ * ```
+ */
+exports.computed = alien_signals_1.computed;
+/**
+ * Re-export of alien-signals `signal` function which creates a basic signal.
+ */
+exports.alienSignal = alien_signals_1.signal;
+/**
+ * Re-export of alien-signals effect function.
+ *
+ * Callback reruns on every signal modification that is used within its callback.
+ *
+ */
+exports.effect = alien_signals_1.effect;

package/dist/deepSignal.d.ts

@@ -1,10 +1,15 @@
 import { DeepPatchJITSubscriber, DeepPatchSubscriber, DeepSignal, DeepSignalOptions } from "./types";
 /** Runtime guard that checks whether a value is a deepSignal proxy. */
-export declare function isDeepSignal(value: any): boolean;
+export declare function isDeepSignal(value: unknown): value is DeepSignal<any>;
 /**
- * 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.
+ * MAIN ENTRY POINT to create a deep reactive proxy for objects, arrays or Sets.
+ *
+ * If input is a deepSignal already and options are provided,
+ * the added subscriberFactories are joined with the existing ones
+ * and `replaceProxiesInBranchOnChange` is or-ed with the current value.
+ *
+ *
+ * @throws if provided with unsupported input types.
  */
 export declare function deepSignal<T extends object>(input: T, options?: DeepSignalOptions): DeepSignal<T>;
 /**
@@ -17,10 +22,19 @@ export declare function subscribeDeepMutations(root: object | symbol, cb: DeepPa
 export declare function getDeepSignalRootId(value: any): symbol | undefined;
 /** Retrieve the current patch version for a deepSignal root (if tracked). */
 export declare function getDeepSignalVersion(root: object | symbol): number | undefined;
-/** Mark an object so deepSignal skips proxying it (shallow boundary). */
+/** Mark an object so deepSignal skips proxying it (shallow boundary).
+ *
+ * @example
+ * ```ts
+ * import { shallow } from "alien-deepsignals";
+ * state.config = shallow({ huge: { blob: true } });
+ * ```
+ */
 export declare function shallow<T extends object>(obj: T): T;
 /** Force a specific synthetic ID to be used for a Set entry prior to insertion. */
 export 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. */
 export declare function addWithId<T>(set: Set<T>, entry: T, id: string | number): T;
+/** Get the original, raw value of a deep signal. */
+export declare function getRaw<T extends object>(value: T | DeepSignal<T>): any;
 //# sourceMappingURL=deepSignal.d.ts.map

package/dist/deepSignal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deepSignal.d.ts","sourceRoot":"","sources":["../src/deepSignal.ts"],"names":[],"mappings":"AAWA,OAAO,EAGH,sBAAsB,EACtB,mBAAmB,EACnB,UAAU,EACV,iBAAiB,EAMpB,MAAM,SAAS,CAAC;AA+qCjB,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAEhD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EACvC,KAAK,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,iBAAiB,GAC5B,UAAU,CAAC,CAAC,CAAC,CAwBf;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAClC,IAAI,EAAE,MAAM,GAAG,MAAM,EACrB,EAAE,EAAE,mBAAmB,GAAG,sBAAsB,EAChD,gBAAgB,GAAE,OAAe,GAClC,MAAM,IAAI,CAoBZ;AAED,yEAAyE;AACzE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,GAAG,GAAG,MAAM,GAAG,SAAS,CAElE;AAED,6EAA6E;AAC7E,wBAAgB,oBAAoB,CAChC,IAAI,EAAE,MAAM,GAAG,MAAM,GACtB,MAAM,GAAG,SAAS,CAIpB;AAED,yEAAyE;AACzE,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAGnD;AAED,mFAAmF;AACnF,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,QAItE;AAED,2FAA2F;AAC3F,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,CAAC,CAa1E"}
+{"version":3,"file":"deepSignal.d.ts","sourceRoot":"","sources":["../src/deepSignal.ts"],"names":[],"mappings":"AAWA,OAAO,EAGH,sBAAsB,EACtB,mBAAmB,EACnB,UAAU,EACV,iBAAiB,EAMpB,MAAM,SAAS,CAAC;AAywCjB,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAAC,GAAG,CAAC,CAErE;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EACvC,KAAK,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,iBAAiB,GAC5B,UAAU,CAAC,CAAC,CAAC,CAwCf;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAClC,IAAI,EAAE,MAAM,GAAG,MAAM,EACrB,EAAE,EAAE,mBAAmB,GAAG,sBAAsB,EAChD,gBAAgB,GAAE,OAAe,GAClC,MAAM,IAAI,CAoBZ;AAED,yEAAyE;AACzE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,GAAG,GAAG,MAAM,GAAG,SAAS,CAElE;AAED,6EAA6E;AAC7E,wBAAgB,oBAAoB,CAChC,IAAI,EAAE,MAAM,GAAG,MAAM,GACtB,MAAM,GAAG,SAAS,CAIpB;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAGnD;AAED,mFAAmF;AACnF,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,QAItE;AAED,2FAA2F;AAC3F,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,CAAC,CAa1E;AAED,oDAAoD;AACpD,wBAAgB,MAAM,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,OAEhE"}