@mmstack/primitives 19.0.0

package/README.md

@@ -0,0 +1,3 @@
+# mmstack/primitives
+
+A library for signal primitives, still working on the docs ;)

package/fesm2022/mmstack-primitives.mjs

@@ -0,0 +1,95 @@
+import { signal, untracked } from '@angular/core';
+
+const { is } = Object;
+function mutable(initial, opt) {
+    const baseEqual = opt?.equal ?? is;
+    let trigger = false;
+    const equal = (a, b) => {
+        if (trigger)
+            return false;
+        return baseEqual(a, b);
+    };
+    const sig = signal(initial, {
+        ...opt,
+        equal,
+    });
+    const internalUpdate = sig.update;
+    sig.mutate = (updater) => {
+        trigger = true;
+        internalUpdate(updater);
+        trigger = false;
+    };
+    sig.inline = (updater) => {
+        sig.mutate((prev) => {
+            updater(prev);
+            return prev;
+        });
+    };
+    return sig;
+}
+/**
+ * Type guard function to check if a given `WritableSignal` is a `MutableSignal`.  This is useful
+ * for situations where you need to conditionally use the `mutate` or `inline` methods.
+ *
+ * @typeParam T - The type of the signal's value (optional, defaults to `any`).
+ * @param value - The `WritableSignal` to check.
+ * @returns `true` if the signal is a `MutableSignal`, `false` otherwise.
+ *
+ * @example
+ * const mySignal = signal(0);
+ * const myMutableSignal = mutable(0);
+ *
+ * if (isMutable(mySignal)) {
+ *   mySignal.mutate(x => x + 1); // This would cause a type error, as mySignal is not a MutableSignal.
+ * }
+ *
+ * if (isMutable(myMutableSignal)) {
+ *   myMutableSignal.mutate(x => x + 1); // This is safe.
+ * }
+ */
+function isMutable(value) {
+    return 'mutate' in value && typeof value.mutate === 'function';
+}
+
+/**
+ * Converts a read-only `Signal` into a `WritableSignal` by providing custom `set` and, optionally, `update` functions.
+ * This can be useful for creating controlled write access to a signal that is otherwise read-only.
+ *
+ * @typeParam T - The type of value held by the signal.
+ *
+ * @param signal - The read-only `Signal` to be made writable.
+ * @param set - A function that will be used to set the signal's value.  This function *must* handle
+ *              the actual update mechanism (e.g., updating a backing store, emitting an event, etc.).
+ * @param update - (Optional) A function that will be used to update the signal's value based on its
+ *                 previous value.  If not provided, a default `update` implementation is used that
+ *                 calls the provided `set` function with the result of the updater function. The
+ *                 default implementation uses `untracked` to avoid creating unnecessary dependencies
+ *                 within the updater function.
+ *
+ * @returns A `WritableSignal` that uses the provided `set` and `update` functions.  The `asReadonly`
+ *          method of the returned signal will still return the original read-only signal.
+ *
+ * @example
+ * // Basic usage: Making a read-only signal writable with a custom set function.
+ * const originalValue = signal({a: 0});
+ * const readOnlySignal = computed(() => originalValue().a);
+ * const writableSignal = toWritable(readOnlySignal, (newValue) => {
+ *  originalValue.update((prev) => { ...prev, a: newValue });
+ * });
+ *
+ * writableSignal.set(5); // sets value of originalValue.a to 5 & triggers all signals
+ */
+function toWritable(signal, set, update) {
+    const internal = signal;
+    internal.asReadonly = () => signal;
+    internal.set = set;
+    internal.update = update ?? ((updater) => set(updater(untracked(internal))));
+    return internal;
+}
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { isMutable, mutable, toWritable };
+//# sourceMappingURL=mmstack-primitives.mjs.map

package/fesm2022/mmstack-primitives.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mmstack-primitives.mjs","sources":["../../../../packages/primitives/src/lib/mutable.ts","../../../../packages/primitives/src/lib/to-writable.ts","../../../../packages/primitives/src/mmstack-primitives.ts"],"sourcesContent":["import {\r\n  signal,\r\n  type CreateSignalOptions,\r\n  type ValueEqualityFn,\r\n  type WritableSignal,\r\n} from '@angular/core';\r\n\r\nconst { is } = Object;\r\n\r\n/**\r\n * A `MutableSignal` is a special type of `WritableSignal` that allows for in-place mutation of its value.\r\n * In addition to the standard `set` and `update` methods, it provides a `mutate` method.  This is useful\r\n * for performance optimization when dealing with complex objects or arrays, as it avoids unnecessary\r\n * object copying.\r\n *\r\n * @typeParam T - The type of value held by the signal.\r\n */\r\nexport type MutableSignal<T> = WritableSignal<T> & {\r\n  /**\r\n   * Mutates the signal's value in-place.  This is similar to `update`, but it's optimized for\r\n   * scenarios where you want to modify the existing object directly rather than creating a new one.\r\n   *\r\n   * @param updater - A function that takes the current value as input and modifies it directly.\r\n   *\r\n   * @example\r\n   * const myArray = mutable([1, 2, 3]);\r\n   * myArray.mutate((arr) => {\r\n   *  arr.push(4);\r\n   *  return arr;\r\n   * }); // myArray() now returns [1, 2, 3, 4]\r\n   */\r\n  mutate: WritableSignal<T>['update'];\r\n\r\n  /**\r\n   * Mutates the signal's value in-place, similar to `mutate`, but with a void-returning value in updater\r\n   * function. This further emphasizes that the mutation is happening inline, improving readability\r\n   * in some cases.\r\n   * @param updater - Function to change to the current value\r\n   * @example\r\n   * const myObject = mutable({ a: 1, b: 2 });\r\n   * myObject.inline((obj) => (obj.a = 3)); // myObject() now returns { a: 3, b: 2 }\r\n   */\r\n  inline: (updater: Parameters<WritableSignal<T>['update']>[0]) => void;\r\n};\r\n\r\n/**\r\n * Creates a `MutableSignal`. This function overloads the standard `signal` function to provide\r\n * the additional `mutate` and `inline` methods.\r\n *\r\n * @typeParam T - The type of value held by the signal.\r\n *\r\n * @param initial - The initial value of the signal.  If no initial value is provided, it defaults to `undefined`.\r\n * @param options - Optional. An object containing signal options, including a custom equality function (`equal`).\r\n *\r\n * @returns A `MutableSignal` instance.\r\n *\r\n * @example\r\n * // Create a mutable signal with an initial value:\r\n * const mySignal = mutable({ count: 0 }) // MutableSignal<{ count: number }>;\r\n *\r\n * // Create a mutable signal with no initial value (starts as undefined):\r\n * const = mutable<number>(); // MutableSignal<number | undefined>\r\n *\r\n * // Create a mutable signal with a custom equality function:\r\n * const myCustomSignal = mutable({ a: 1 }, { equal: (a, b) => a.a === b.a });\r\n */\r\nexport function mutable<T>(): MutableSignal<T | undefined>;\r\nexport function mutable<T>(initial: T): MutableSignal<T>;\r\nexport function mutable<T>(\r\n  initial: T,\r\n  opt?: CreateSignalOptions<T>,\r\n): MutableSignal<T>;\r\n\r\nexport function mutable<T>(\r\n  initial?: T,\r\n  opt?: CreateSignalOptions<T>,\r\n): MutableSignal<T> {\r\n  const baseEqual = opt?.equal ?? is;\r\n  let trigger = false;\r\n\r\n  const equal: ValueEqualityFn<T | undefined> = (a, b) => {\r\n    if (trigger) return false;\r\n    return baseEqual(a, b);\r\n  };\r\n\r\n  const sig = signal<T | undefined>(initial, {\r\n    ...opt,\r\n    equal,\r\n  }) as MutableSignal<T>;\r\n\r\n  const internalUpdate = sig.update;\r\n\r\n  sig.mutate = (updater) => {\r\n    trigger = true;\r\n    internalUpdate(updater);\r\n    trigger = false;\r\n  };\r\n\r\n  sig.inline = (updater) => {\r\n    sig.mutate((prev) => {\r\n      updater(prev);\r\n      return prev;\r\n    });\r\n  };\r\n\r\n  return sig;\r\n}\r\n\r\n/**\r\n * Type guard function to check if a given `WritableSignal` is a `MutableSignal`.  This is useful\r\n * for situations where you need to conditionally use the `mutate` or `inline` methods.\r\n *\r\n * @typeParam T - The type of the signal's value (optional, defaults to `any`).\r\n * @param value - The `WritableSignal` to check.\r\n * @returns `true` if the signal is a `MutableSignal`, `false` otherwise.\r\n *\r\n * @example\r\n * const mySignal = signal(0);\r\n * const myMutableSignal = mutable(0);\r\n *\r\n * if (isMutable(mySignal)) {\r\n *   mySignal.mutate(x => x + 1); // This would cause a type error, as mySignal is not a MutableSignal.\r\n * }\r\n *\r\n * if (isMutable(myMutableSignal)) {\r\n *   myMutableSignal.mutate(x => x + 1); // This is safe.\r\n * }\r\n */\r\nexport function isMutable<T = any>(\r\n  value: WritableSignal<T>,\r\n): value is MutableSignal<T> {\r\n  return 'mutate' in value && typeof value.mutate === 'function';\r\n}\r\n","import { Signal, untracked, WritableSignal } from '@angular/core';\n\n/**\n * Converts a read-only `Signal` into a `WritableSignal` by providing custom `set` and, optionally, `update` functions.\n * This can be useful for creating controlled write access to a signal that is otherwise read-only.\n *\n * @typeParam T - The type of value held by the signal.\n *\n * @param signal - The read-only `Signal` to be made writable.\n * @param set - A function that will be used to set the signal's value.  This function *must* handle\n *              the actual update mechanism (e.g., updating a backing store, emitting an event, etc.).\n * @param update - (Optional) A function that will be used to update the signal's value based on its\n *                 previous value.  If not provided, a default `update` implementation is used that\n *                 calls the provided `set` function with the result of the updater function. The\n *                 default implementation uses `untracked` to avoid creating unnecessary dependencies\n *                 within the updater function.\n *\n * @returns A `WritableSignal` that uses the provided `set` and `update` functions.  The `asReadonly`\n *          method of the returned signal will still return the original read-only signal.\n *\n * @example\n * // Basic usage: Making a read-only signal writable with a custom set function.\n * const originalValue = signal({a: 0});\n * const readOnlySignal = computed(() => originalValue().a);\n * const writableSignal = toWritable(readOnlySignal, (newValue) => {\n *  originalValue.update((prev) => { ...prev, a: newValue });\n * });\n *\n * writableSignal.set(5); // sets value of originalValue.a to 5 & triggers all signals\n */\nexport function toWritable<T>(\n  signal: Signal<T>,\n  set: (value: T) => void,\n  update?: (updater: (value: T) => T) => void,\n): WritableSignal<T> {\n  const internal = signal as WritableSignal<T>;\n  internal.asReadonly = () => signal;\n  internal.set = set;\n  internal.update = update ?? ((updater) => set(updater(untracked(internal))));\n\n  return internal;\n}\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './index';\n"],"names":[],"mappings":";;AAOA,MAAM,EAAE,EAAE,EAAE,GAAG,MAAM;AAkEL,SAAA,OAAO,CACrB,OAAW,EACX,GAA4B,EAAA;AAE5B,IAAA,MAAM,SAAS,GAAG,GAAG,EAAE,KAAK,IAAI,EAAE;IAClC,IAAI,OAAO,GAAG,KAAK;AAEnB,IAAA,MAAM,KAAK,GAAmC,CAAC,CAAC,EAAE,CAAC,KAAI;AACrD,QAAA,IAAI,OAAO;AAAE,YAAA,OAAO,KAAK;AACzB,QAAA,OAAO,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC;AACxB,KAAC;AAED,IAAA,MAAM,GAAG,GAAG,MAAM,CAAgB,OAAO,EAAE;AACzC,QAAA,GAAG,GAAG;QACN,KAAK;AACN,KAAA,CAAqB;AAEtB,IAAA,MAAM,cAAc,GAAG,GAAG,CAAC,MAAM;AAEjC,IAAA,GAAG,CAAC,MAAM,GAAG,CAAC,OAAO,KAAI;QACvB,OAAO,GAAG,IAAI;QACd,cAAc,CAAC,OAAO,CAAC;QACvB,OAAO,GAAG,KAAK;AACjB,KAAC;AAED,IAAA,GAAG,CAAC,MAAM,GAAG,CAAC,OAAO,KAAI;AACvB,QAAA,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,KAAI;YAClB,OAAO,CAAC,IAAI,CAAC;AACb,YAAA,OAAO,IAAI;AACb,SAAC,CAAC;AACJ,KAAC;AAED,IAAA,OAAO,GAAG;AACZ;AAEA;;;;;;;;;;;;;;;;;;;AAmBG;AACG,SAAU,SAAS,CACvB,KAAwB,EAAA;IAExB,OAAO,QAAQ,IAAI,KAAK,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,UAAU;AAChE;;AClIA;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BG;SACa,UAAU,CACxB,MAAiB,EACjB,GAAuB,EACvB,MAA2C,EAAA;IAE3C,MAAM,QAAQ,GAAG,MAA2B;AAC5C,IAAA,QAAQ,CAAC,UAAU,GAAG,MAAM,MAAM;AAClC,IAAA,QAAQ,CAAC,GAAG,GAAG,GAAG;IAClB,QAAQ,CAAC,MAAM,GAAG,MAAM,KAAK,CAAC,OAAO,KAAK,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;AAE5E,IAAA,OAAO,QAAQ;AACjB;;ACzCA;;AAEG;;;;"}

package/index.d.ts

@@ -0,0 +1,2 @@
+export * from './lib/mutable';
+export * from './lib/to-writable';

package/lib/mutable.d.ts

@@ -0,0 +1,80 @@
+import { type CreateSignalOptions, type WritableSignal } from '@angular/core';
+/**
+ * A `MutableSignal` is a special type of `WritableSignal` that allows for in-place mutation of its value.
+ * In addition to the standard `set` and `update` methods, it provides a `mutate` method.  This is useful
+ * for performance optimization when dealing with complex objects or arrays, as it avoids unnecessary
+ * object copying.
+ *
+ * @typeParam T - The type of value held by the signal.
+ */
+export type MutableSignal<T> = WritableSignal<T> & {
+    /**
+     * Mutates the signal's value in-place.  This is similar to `update`, but it's optimized for
+     * scenarios where you want to modify the existing object directly rather than creating a new one.
+     *
+     * @param updater - A function that takes the current value as input and modifies it directly.
+     *
+     * @example
+     * const myArray = mutable([1, 2, 3]);
+     * myArray.mutate((arr) => {
+     *  arr.push(4);
+     *  return arr;
+     * }); // myArray() now returns [1, 2, 3, 4]
+     */
+    mutate: WritableSignal<T>['update'];
+    /**
+     * Mutates the signal's value in-place, similar to `mutate`, but with a void-returning value in updater
+     * function. This further emphasizes that the mutation is happening inline, improving readability
+     * in some cases.
+     * @param updater - Function to change to the current value
+     * @example
+     * const myObject = mutable({ a: 1, b: 2 });
+     * myObject.inline((obj) => (obj.a = 3)); // myObject() now returns { a: 3, b: 2 }
+     */
+    inline: (updater: Parameters<WritableSignal<T>['update']>[0]) => void;
+};
+/**
+ * Creates a `MutableSignal`. This function overloads the standard `signal` function to provide
+ * the additional `mutate` and `inline` methods.
+ *
+ * @typeParam T - The type of value held by the signal.
+ *
+ * @param initial - The initial value of the signal.  If no initial value is provided, it defaults to `undefined`.
+ * @param options - Optional. An object containing signal options, including a custom equality function (`equal`).
+ *
+ * @returns A `MutableSignal` instance.
+ *
+ * @example
+ * // Create a mutable signal with an initial value:
+ * const mySignal = mutable({ count: 0 }) // MutableSignal<{ count: number }>;
+ *
+ * // Create a mutable signal with no initial value (starts as undefined):
+ * const = mutable<number>(); // MutableSignal<number | undefined>
+ *
+ * // Create a mutable signal with a custom equality function:
+ * const myCustomSignal = mutable({ a: 1 }, { equal: (a, b) => a.a === b.a });
+ */
+export declare function mutable<T>(): MutableSignal<T | undefined>;
+export declare function mutable<T>(initial: T): MutableSignal<T>;
+export declare function mutable<T>(initial: T, opt?: CreateSignalOptions<T>): MutableSignal<T>;
+/**
+ * Type guard function to check if a given `WritableSignal` is a `MutableSignal`.  This is useful
+ * for situations where you need to conditionally use the `mutate` or `inline` methods.
+ *
+ * @typeParam T - The type of the signal's value (optional, defaults to `any`).
+ * @param value - The `WritableSignal` to check.
+ * @returns `true` if the signal is a `MutableSignal`, `false` otherwise.
+ *
+ * @example
+ * const mySignal = signal(0);
+ * const myMutableSignal = mutable(0);
+ *
+ * if (isMutable(mySignal)) {
+ *   mySignal.mutate(x => x + 1); // This would cause a type error, as mySignal is not a MutableSignal.
+ * }
+ *
+ * if (isMutable(myMutableSignal)) {
+ *   myMutableSignal.mutate(x => x + 1); // This is safe.
+ * }
+ */
+export declare function isMutable<T = any>(value: WritableSignal<T>): value is MutableSignal<T>;

package/lib/to-writable.d.ts

@@ -0,0 +1,30 @@
+import { Signal, WritableSignal } from '@angular/core';
+/**
+ * Converts a read-only `Signal` into a `WritableSignal` by providing custom `set` and, optionally, `update` functions.
+ * This can be useful for creating controlled write access to a signal that is otherwise read-only.
+ *
+ * @typeParam T - The type of value held by the signal.
+ *
+ * @param signal - The read-only `Signal` to be made writable.
+ * @param set - A function that will be used to set the signal's value.  This function *must* handle
+ *              the actual update mechanism (e.g., updating a backing store, emitting an event, etc.).
+ * @param update - (Optional) A function that will be used to update the signal's value based on its
+ *                 previous value.  If not provided, a default `update` implementation is used that
+ *                 calls the provided `set` function with the result of the updater function. The
+ *                 default implementation uses `untracked` to avoid creating unnecessary dependencies
+ *                 within the updater function.
+ *
+ * @returns A `WritableSignal` that uses the provided `set` and `update` functions.  The `asReadonly`
+ *          method of the returned signal will still return the original read-only signal.
+ *
+ * @example
+ * // Basic usage: Making a read-only signal writable with a custom set function.
+ * const originalValue = signal({a: 0});
+ * const readOnlySignal = computed(() => originalValue().a);
+ * const writableSignal = toWritable(readOnlySignal, (newValue) => {
+ *  originalValue.update((prev) => { ...prev, a: newValue });
+ * });
+ *
+ * writableSignal.set(5); // sets value of originalValue.a to 5 & triggers all signals
+ */
+export declare function toWritable<T>(signal: Signal<T>, set: (value: T) => void, update?: (updater: (value: T) => T) => void): WritableSignal<T>;

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@mmstack/primitives",
+  "version": "19.0.0",
+  "peerDependencies": {
+    "@angular/core": "19.2.3"
+  },
+  "sideEffects": false,
+  "module": "fesm2022/mmstack-primitives.mjs",
+  "typings": "index.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./fesm2022/mmstack-primitives.mjs"
+    }
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  }
+}