mates-devtools 0.1.0-beta.1

package/dist/types/lib/Mutables/atom/createTimedAtom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createTimedAtom.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/atom/createTimedAtom.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,QAAQ,EAAQ,MAAM,QAAQ,CAAC;AAE9D,KAAK,cAAc,GAAG,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACtD,EAAE,EAAE,CAAC,EACL,KAAK,EAAE,MAAM,KACV,CAAC,GAAG;IAAE,MAAM,EAAE,MAAM,IAAI,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,IAAI,CAAA;CAAE,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,EAC/B,oBAAoB,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,EACnC,OAAO,MAAM,EACb,UAAU,cAAc,EACxB,SAAS,UAAU,KAClB,QAAQ,CAAC,CAAC,CAkCZ,CAAC"}

package/dist/types/lib/Mutables/atom/debouncedAtom.d.ts

@@ -0,0 +1,37 @@
+import type { AtomConfig, AtomType } from "./atom";
+/**
+ * Creates a debounced reactive atom whose `set()` and `update()` calls are
+ * delayed by `delay` ms. When multiple calls arrive within the delay window,
+ * only the **last** one fires — earlier calls are cancelled.
+ *
+ * Accepts either a plain initial value or a source {@link AtomType}. When a
+ * source atom is provided, the debounced atom mirrors the source's value,
+ * applying the debounce to every propagated change.
+ *
+ * Cleanup of the internal debounce timer is registered automatically and runs
+ * when the atom is disposed.
+ *
+ * @param initialAtomOrState - A plain initial value, or a source atom whose
+ *   updates will be mirrored with debouncing.
+ * @param delay - How long to wait (in milliseconds) after the last call before
+ *   the value is actually committed.
+ * @param config - Optional atom configuration forwarded to the underlying
+ *   {@link atom} instance.
+ * @returns A new {@link AtomType} whose writes are debounced.
+ *
+ * @example
+ * // Standalone debounced atom — only the last rapid set fires after 300 ms:
+ * const search = debouncedAtom("", 300);
+ * search.set("he");
+ * search.set("hel");
+ * search.set("hello"); // only this fires after 300 ms
+ * search();            // "hello"
+ *
+ * @example
+ * // Mirror a source atom with debouncing:
+ * const raw = atom("");
+ * const debounced = debouncedAtom(raw, 300);
+ * // Every time `raw` changes, `debounced` receives the latest value 300 ms later.
+ */
+export declare const debouncedAtom: <T>(initialAtomOrState: T | AtomType<T>, delay: number, config?: AtomConfig) => AtomType<T>;
+//# sourceMappingURL=debouncedAtom.d.ts.map

package/dist/types/lib/Mutables/atom/debouncedAtom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debouncedAtom.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/atom/debouncedAtom.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAGnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,aAAa,GAAI,CAAC,EAC7B,oBAAoB,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,EACnC,OAAO,MAAM,EACb,SAAS,UAAU,KAClB,QAAQ,CAAC,CAAC,CAEZ,CAAC"}

package/dist/types/lib/Mutables/atom/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./atom";
+export * from "./createTimedAtom";
+export * from "./debouncedAtom";
+export * from "./atom";
+export * from "./mapAtom";
+export * from "./setAtom";
+export * from "./storageAtom";
+export * from "./throttledAtom";
+export * from "./titleAtom";
+//# sourceMappingURL=index.d.ts.map

package/dist/types/lib/Mutables/atom/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/atom/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC"}

package/dist/types/lib/Mutables/atom/mapAtom.d.ts

@@ -0,0 +1,105 @@
+import { type AtomConfig } from "./atom";
+/**
+ * A reactive `Map<K, V>` returned by `mapAtom`.
+ *
+ * Extends the standard `Map<K, V>` with two extra mutation methods:
+ *
+ * - `update(fn)`         — pass the live map instance into `fn` so you can
+ *                          call any Map method directly (set/delete/clear/get).
+ *                          `fn` returns nothing; mutations are in-place.
+ *                          One notification fires after `fn` returns.
+ *
+ * - `updateItem(key, fn)` — get the object stored at `key` and pass it to
+ *                           `fn` for in-place mutation (no return value).
+ *                           Only meaningful when `V` is an object type.
+ *                           Use `map.set(key, newValue)` to replace primitives.
+ */
+export type MapAtomType<K, V> = Map<K, V> & {
+    /**
+     * Receive the live `Map<K, V>` instance and mutate it directly.
+     * `fn` may call any Map method (`set`, `delete`, `clear`, `get`, …).
+     * No return value — mutations are in-place.
+     * One reactive notification fires after `fn` returns.
+     *
+     * ```ts
+     * const users = mapAtom([["alice", { name: "Alice", score: 0 }]]);
+     *
+     * users.update((map) => {
+     *   map.get("alice")!.score += 10;   // mutate a nested object
+     *   map.set("bob", { name: "Bob", score: 5 }); // add an entry
+     *   map.delete("carol");             // remove an entry
+     * });
+     * ```
+     *
+     * @param fn - Receives the live map and should mutate it in place.
+     * @returns The map instance for chaining.
+     */
+    update(fn: (map: Map<K, V>) => void): MapAtomType<K, V>;
+    /**
+     * Get the object stored at `key` and pass it to `fn` for in-place mutation.
+     * `fn` returns nothing — the value is mutated directly.
+     * One reactive notification fires after `fn` returns.
+     *
+     * Only meaningful when `V` is an object type. To replace a primitive value
+     * use `map.set(key, newValue)` instead.
+     * No-op when `key` is absent or its value is not an object.
+     *
+     * ```ts
+     * const users = mapAtom([["alice", { name: "Alice", age: 30 }]]);
+     *
+     * users.updateItem("alice", (user) => {
+     *   user.age += 1;
+     *   user.name = user.name.toUpperCase();
+     * });
+     *
+     * users.get("alice"); // { name: "ALICE", age: 31 }
+     * ```
+     *
+     * @param key - The key whose value should be mutated.
+     * @param fn  - Receives the current value and should mutate it in place.
+     * @returns The map instance for chaining.
+     */
+    updateItem(key: K, fn: (value: V) => void): MapAtomType<K, V>;
+};
+/**
+ * Creates a reactive `Map<K, V>` whose mutation methods notify subscribers
+ * and whose read methods register the map as a tracked dependency.
+ *
+ * **Mutations** — each triggers a notification so subscribers are informed:
+ * - `set(key, value)`, `delete(key)`, `clear()`
+ * - `update(fn)`         — in-place whole-map mutation
+ * - `updateItem(key, fn)` — in-place mutation of a single object value
+ *
+ * **Reads** — each registers a reactive dependency:
+ * - `get(key)`, `has(key)`, `size`, `entries()`, `values()`, `keys()`,
+ *   `forEach()`, `[Symbol.iterator]()`
+ *
+ * The underlying atom is exposed via two non-enumerable properties:
+ * - `m.__isAtom___` — the raw `AtomType<Map<K, V>>` for manual subscriptions
+ * - `m.__version__`  — current version counter of the underlying atom
+ *
+ * @param initialState - Optional `[key, value]` pairs (same as `Map` ctor).
+ * @param config       - Optional atom configuration.
+ * @returns A `MapAtomType<K, V>` instance with reactive tracking.
+ *
+ * @example
+ * ```ts
+ * const scores = mapAtom([["alice", { value: 10 }], ["bob", { value: 5 }]]);
+ *
+ * // Replace a value (use set for primitives too)
+ * scores.set("carol", { value: 3 });
+ *
+ * // Mutate the whole map in one go
+ * scores.update((map) => {
+ *   map.get("alice")!.value += 1;
+ *   map.delete("bob");
+ * });
+ *
+ * // Mutate one entry in place
+ * scores.updateItem("alice", (entry) => {
+ *   entry.value *= 2;
+ * });
+ * ```
+ */
+export declare const mapAtom: <K, V>(initialState?: [K, V][], config?: AtomConfig) => MapAtomType<K, V>;
+//# sourceMappingURL=mapAtom.d.ts.map

package/dist/types/lib/Mutables/atom/mapAtom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapAtom.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/atom/mapAtom.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAQ,MAAM,QAAQ,CAAC;AAI/C;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,EAAE,CAAC,IAAI,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG;IAC1C;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,IAAI,GAAG,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAExD;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,UAAU,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CAC/D,CAAC;AAIF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,EAAE,CAAC,EAC1B,eAAc,CAAC,CAAC,EAAE,CAAC,CAAC,EAAO,EAC3B,SAAS,UAAU,KAClB,WAAW,CAAC,CAAC,EAAE,CAAC,CA0JlB,CAAC"}

package/dist/types/lib/Mutables/atom/setAtom.d.ts

@@ -0,0 +1,107 @@
+import { type AtomConfig } from "./atom";
+/**
+ * A reactive `Set<T>` returned by `setAtom`.
+ *
+ * Extends the standard `Set<T>` with two extra mutation methods:
+ *
+ * - `update(fn)`         — pass the live set instance into `fn` so you can
+ *                          call any Set method directly (add/delete/clear/has).
+ *                          `fn` returns nothing; mutations are in-place.
+ *                          One notification fires after `fn` returns.
+ *
+ * - `updateItem(item, fn)` — find the object stored at `item` (by reference)
+ *                            and pass it to `fn` for in-place mutation.
+ *                            Only meaningful when `T` is an object type.
+ *                            Use `set.delete(old); set.add(new)` to replace
+ *                            primitive values.
+ */
+export type SetAtomType<T> = Set<T> & {
+    /**
+     * Receive the live `Set<T>` instance and mutate it directly.
+     * `fn` may call any Set method (`add`, `delete`, `clear`, `has`, …).
+     * No return value — mutations are in-place.
+     * One reactive notification fires after `fn` returns.
+     *
+     * ```ts
+     * const ids = setAtom([1, 2, 3]);
+     *
+     * ids.update((set) => {
+     *   set.add(4);
+     *   set.delete(1);
+     * });
+     * ```
+     *
+     * @param fn - Receives the live set and should mutate it in place.
+     * @returns The set instance for chaining.
+     */
+    update(fn: (set: Set<T>) => void): SetAtomType<T>;
+    /**
+     * Find `item` in the set (by reference) and pass it to `fn` for in-place
+     * mutation. `fn` returns nothing — the object is mutated directly.
+     * One reactive notification fires after `fn` returns.
+     *
+     * Only meaningful when `T` is an object type. Because Set uses reference
+     * equality the mutated object stays in the set automatically — no
+     * delete/re-add needed.
+     * No-op when `item` is not an object or is `null`.
+     *
+     * ```ts
+     * const alice = { id: 1, name: "Alice", score: 0 };
+     * const users = setAtom([alice, { id: 2, name: "Bob", score: 5 }]);
+     *
+     * users.updateItem(alice, (user) => {
+     *   user.score += 10;
+     *   user.name = user.name.toUpperCase();
+     * });
+     *
+     * // alice is still in the set, now { id: 1, name: "ALICE", score: 10 }
+     * ```
+     *
+     * @param item - The object already stored in the set (matched by reference).
+     * @param fn   - Receives the item and should mutate it in place.
+     * @returns The set instance for chaining.
+     */
+    updateItem(item: T, fn: (item: T) => void): SetAtomType<T>;
+};
+/**
+ * Creates a reactive `Set<T>` whose mutations automatically notify subscribers.
+ *
+ * **Mutations** — each triggers a notification so subscribers are informed:
+ * - `add(value)`, `delete(value)`, `clear()`
+ * - `update(fn)`          — in-place whole-set mutation
+ * - `updateItem(item, fn)` — in-place mutation of a single object item
+ *
+ * **Reads** — each registers a reactive dependency:
+ * - `has(value)`, `size`, `entries()`, `values()`, `keys()`,
+ *   `forEach()`, `[Symbol.iterator]()`
+ *
+ * The underlying atom is accessible via two non-enumerable properties:
+ * - `s.__isAtom___` — the raw `AtomType<Set<T>>` for manual subscriptions
+ * - `s.__version__`  — current version counter of the underlying atom
+ *
+ * @param initialState - Optional array of initial values (defaults to `[]`).
+ * @param config       - Optional atom configuration.
+ * @returns A `SetAtomType<T>` instance with reactive tracking.
+ *
+ * @example
+ * ```ts
+ * const tags = setAtom(["typescript", "javascript"]);
+ *
+ * // Replace / add primitives
+ * tags.add("rust");
+ * tags.delete("javascript");
+ *
+ * // Mutate the whole set in one go
+ * tags.update((set) => {
+ *   set.add("go");
+ *   set.delete("typescript");
+ * });
+ *
+ * // Mutate one object item in place
+ * const user = { id: 1, name: "Alice" };
+ * const users = setAtom([user]);
+ * users.updateItem(user, (u) => { u.name = "ALICE"; });
+ * ```
+ */
+export declare const setAtom: <T>(initialState?: T[], config?: AtomConfig) => SetAtomType<T>;
+//# sourceMappingURL=setAtom.d.ts.map

package/dist/types/lib/Mutables/atom/setAtom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setAtom.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/atom/setAtom.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAQ,MAAM,QAAQ,CAAC;AAI/C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG;IACpC;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;IAElD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,UAAU,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;CAC5D,CAAC;AAIF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,EACvB,eAAc,CAAC,EAAO,EACtB,SAAS,UAAU,KAClB,WAAW,CAAC,CAAC,CAmJf,CAAC"}

package/dist/types/lib/Mutables/atom/storageAtom.d.ts

@@ -0,0 +1,44 @@
+import { type AtomType } from "./atom";
+export type StorageValue = Record<string, unknown>;
+export type StorageAtomType = AtomType<StorageValue | null>;
+/**
+ * A reactive atom backed by `localStorage["mates"]`.
+ *
+ * A single shared instance — import and use directly, no factory call needed.
+ *
+ * - Hydrates from `localStorage` on module load.
+ * - Every `set()` / `update()` persists the new value to `localStorage["mates"]`.
+ * - Changes made in another tab are synced automatically via the `storage` event.
+ * - Only manages the single `"mates"` key — it does not expose or interact with
+ *   any other localStorage entries.
+ *
+ * @example
+ * import { lsAtom } from "./storageAtom";
+ *
+ * lsAtom.set({ theme: "dark", lang: "en" });
+ * lsAtom.update(d => { d.lang = "fr"; });
+ * lsAtom();          // { theme: "dark", lang: "fr" }
+ * lsAtom.get();      // same
+ * lsAtom.val;        // same
+ */
+export declare const lsAtom: StorageAtomType;
+/**
+ * A reactive atom backed by `sessionStorage["mates"]`.
+ *
+ * A single shared instance — import and use directly, no factory call needed.
+ *
+ * - Hydrates from `sessionStorage` on module load.
+ * - Every `set()` / `update()` persists the new value to `sessionStorage["mates"]`.
+ * - `sessionStorage` is tab-scoped so no cross-tab sync occurs.
+ * - Only manages the single `"mates"` key — it does not expose or interact with
+ *   any other sessionStorage entries.
+ *
+ * @example
+ * import { ssAtom } from "./storageAtom";
+ *
+ * ssAtom.set({ cart: [], user: null });
+ * ssAtom.update(d => { d.cart = [item]; });
+ * ssAtom();          // { cart: [item], user: null }
+ */
+export declare const ssAtom: StorageAtomType;
+//# sourceMappingURL=storageAtom.d.ts.map

package/dist/types/lib/Mutables/atom/storageAtom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storageAtom.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/atom/storageAtom.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAQ,MAAM,QAAQ,CAAC;AAI7C,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACnD,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;AAwI5D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,MAAM,EAAE,eAMpB,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,MAAM,EAAE,eAMpB,CAAC"}

package/dist/types/lib/Mutables/atom/throttledAtom.d.ts

@@ -0,0 +1,37 @@
+import type { AtomConfig, AtomType } from "./atom";
+/**
+ * Creates a throttled reactive atom — at most one `set()` or `update()` call
+ * fires per `delay` ms window. Additional calls within the same window are
+ * dropped; the first call in each window goes through immediately.
+ *
+ * Accepts either a plain initial value or a source {@link AtomType}. When a
+ * source atom is provided the returned atom mirrors the source's value, but
+ * propagation to subscribers is throttled so that downstream reactions fire at
+ * most once per `delay` ms regardless of how frequently the source changes.
+ *
+ * Cleanup of the internal throttle timer is registered automatically via
+ * `registerCleanup` — no manual teardown is required.
+ *
+ * @param initialAtomOrState - The initial value for the atom, or a source atom
+ *   whose value this atom should mirror with throttling applied.
+ * @param delay - The minimum number of milliseconds that must elapse between
+ *   two consecutive `set()`/`update()` calls being forwarded to subscribers.
+ * @param config - Optional {@link AtomConfig} forwarded to the underlying atom.
+ * @returns A new {@link AtomType} whose `set` and `update` methods are
+ *   throttled by `delay` ms.
+ *
+ * @example
+ * // Throttle direct writes — only one set fires per 100 ms window:
+ * const scrollY = throttledAtom(0, 100);
+ * window.addEventListener("scroll", () => scrollY.set(window.scrollY));
+ * // Only one set fires per 100ms no matter how fast the user scrolls
+ *
+ * @example
+ * // Mirror a source atom with throttling applied:
+ * const rawScroll = atom(0);
+ * const throttled = throttledAtom(rawScroll, 100);
+ * // throttled mirrors rawScroll but notifies its own subscribers at most
+ * // once every 100 ms
+ */
+export declare const throttledAtom: <T>(initialAtomOrState: T | AtomType<T>, delay: number, config?: AtomConfig) => AtomType<T>;
+//# sourceMappingURL=throttledAtom.d.ts.map

package/dist/types/lib/Mutables/atom/throttledAtom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"throttledAtom.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/atom/throttledAtom.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAGnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,aAAa,GAAI,CAAC,EAC7B,oBAAoB,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,EACnC,OAAO,MAAM,EACb,SAAS,UAAU,KAClB,QAAQ,CAAC,CAAC,CAEZ,CAAC"}

package/dist/types/lib/Mutables/atom/titleAtom.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A singleton reactive atom that mirrors `document.title`.
+ *
+ * Setting this atom automatically updates the browser tab title via an
+ * internal effect. Reading it inside a memo, effect, or component will
+ * re-run that context whenever the title changes.
+ *
+ * On SSR (environments where `document` is not defined) the initial value
+ * is `""` and writes to the atom are tracked reactively but do not touch
+ * any DOM.
+ *
+ * @example
+ * ```ts
+ * titleAtom.set("My App - Dashboard"); // document.title === "My App - Dashboard"
+ * titleAtom.get(); // "My App - Dashboard"
+ * // Reading titleAtom() in a component will re-render whenever the title changes
+ * ```
+ */
+export declare const titleAtom: import("./atom").AtomType<string>;
+//# sourceMappingURL=titleAtom.d.ts.map

package/dist/types/lib/Mutables/atom/titleAtom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"titleAtom.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/atom/titleAtom.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,SAAS,mCAAqB,CAAC"}

package/dist/types/lib/Mutables/effect/effect.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Creates a reactive side-effect that runs immediately and re-runs whenever
+ * its dependencies change.
+ *
+ * - Runs `fn` immediately on creation.
+ * - Automatically tracks any atoms/stores read inside `fn` as dependencies.
+ * - Re-runs `fn` whenever any dependency changes (scheduled via the effect scheduler).
+ * - If `fn` returns a cleanup function, that cleanup runs before the next execution
+ *   and when the effect is disposed.
+ * - Returns a `dispose` function — call it to stop the effect and run the final cleanup.
+ * - `fn` is marked `__isEffect__ = true` so the reactive runner knows it supports cleanup.
+ * - Must NOT be called inside a template function (restricted context guard applies
+ *   via `createReactiveRunner`).
+ *
+ * @param fn - The side-effect function to run. May return a cleanup function that
+ *             is called before the next run and on disposal.
+ * @returns A `dispose` function that stops the effect and runs the final cleanup.
+ *
+ * @example
+ * const count = atom(0);
+ *
+ * const stop = effect(() => {
+ *   console.log("count is", count()); // runs immediately, then on every change
+ *   return () => console.log("cleanup"); // runs before next execution
+ * });
+ *
+ * count.set(1); // logs "cleanup", then "count is 1"
+ * stop();        // dispose — runs final cleanup
+ */
+export declare function effect(fn: () => (() => void) | undefined | void): () => void;
+//# sourceMappingURL=effect.d.ts.map

package/dist/types/lib/Mutables/effect/effect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effect.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/effect/effect.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,IAAI,CAQ5E"}

package/dist/types/lib/Mutables/effect/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./effect";
+//# sourceMappingURL=index.d.ts.map

package/dist/types/lib/Mutables/effect/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/effect/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC"}

package/dist/types/lib/Mutables/events/events.d.ts

@@ -0,0 +1,123 @@
+type EventHandler<T = any> = (data: T) => void;
+export interface EventType<T = any> {
+    __subscribe: (fn: EventHandler<T>) => () => void;
+    trigger: (data?: T) => void;
+    name: string;
+    __isEvent___: true;
+}
+/**
+ * Creates a typed pub/sub event.
+ *
+ * @param name - Optional human-readable name for the event. If omitted, a random
+ *               string is generated. The name appears in devtools traces.
+ *
+ * @remarks
+ * - `trigger(data?)` — fires all subscribers synchronously and logs to devtools.
+ * - `__subscribe(fn)` — registers a handler and returns an unsubscribe function.
+ * - Pass the event as a dependency to `on()` so the callback re-runs whenever
+ *   the event fires: `on(callback, [myEvent])`.
+ * - Cannot be created inside a template function (a restricted-context guard is
+ *   applied via `assertNotInRestrictedContext`).
+ *
+ * @example
+ * ```ts
+ * const userLoggedIn = event<{ userId: string }>("user:login");
+ *
+ * const unsub = userLoggedIn.__subscribe((data) => {
+ *   console.log("logged in:", data.userId);
+ * });
+ *
+ * userLoggedIn.trigger({ userId: "abc123" });
+ * unsub(); // stop listening
+ * ```
+ */
+export declare const event: <T = any>(name?: string) => EventType<T>;
+export interface ChannelType<T = any> {
+    join: (handler: EventHandler<T>) => {
+        leave: () => void;
+        send: (data?: T) => void;
+    };
+    name?: string;
+    __isChannel___: true;
+}
+type CleanupHandler<T = any> = (data: T) => (() => void) | undefined;
+export interface CleanupEventType<T = any> {
+    __subscribe: (fn: CleanupHandler<T>) => () => void;
+    trigger: (data?: T) => void;
+    cleanup: () => void;
+    cleanupAndClearSubs: () => void;
+    readonly hasSubscribers: boolean;
+    name: string;
+    __isCleanupEvent___: true;
+    __isEvent___: true;
+}
+/**
+ * Like `event`, but each subscriber can return a cleanup function that runs
+ * automatically before the handler is called again on the next `trigger()`.
+ *
+ * @param name - Optional human-readable name for the event. If omitted, a random
+ *               string is generated. The name appears in devtools traces.
+ *
+ * @remarks
+ * - `trigger(data?)` — for every subscriber: runs its previous cleanup (if any),
+ *   then calls the handler with the new data, and stores whatever the handler
+ *   returns as the next cleanup.
+ * - `__subscribe(fn)` — registers a handler; returns an unsubscribe function that
+ *   also runs any pending cleanup for that handler.
+ * - `cleanup()` — runs all stored cleanups without removing subscribers.
+ * - `cleanupAndClearSubs()` — runs all stored cleanups AND removes every subscriber.
+ * - `hasSubscribers` — boolean getter; `true` when at least one subscriber is registered.
+ * - Cannot be created inside a template function (restricted-context guard applies).
+ *
+ * @example
+ * ```ts
+ * const tabVisible = cleanupEvent<boolean>("tab:visible");
+ *
+ * tabVisible.__subscribe((visible) => {
+ *   const timer = setInterval(() => {}, 1000);
+ *   return () => clearInterval(timer); // runs before next trigger
+ * });
+ *
+ * tabVisible.trigger(true);
+ * tabVisible.trigger(false);        // runs previous cleanup first
+ * tabVisible.cleanup();             // run all cleanups without removing subs
+ * tabVisible.cleanupAndClearSubs(); // run cleanups + remove all subs
+ * ```
+ */
+export declare const cleanupEvent: <T = any>(name?: string) => CleanupEventType<T>;
+/**
+ * Creates a many-to-many pub/sub channel where any member can broadcast to all
+ * OTHER members — the sender never receives its own message.
+ *
+ * @remarks
+ * - `join(handler)` — adds `handler` to the channel and returns `{ send, leave }`.
+ *   - `send(data?)` — broadcasts `data` to every member except the caller.
+ *   - `leave()` — removes the handler from the channel.
+ * - Auto-cleanup: when `join()` is called inside a component, `leave()` is
+ *   automatically registered via `registerCleanup` so the handler is removed when
+ *   the component unmounts.
+ * - Cannot be created inside a template function, and `join()` also enforces the
+ *   same restricted-context guard.
+ *
+ * @example
+ * ```ts
+ * const chat = channel<string>();
+ *
+ * // Component A joins:
+ * const { send: sendA, leave: leaveA } = chat.join((msg) => {
+ *   console.log("A received:", msg);
+ * });
+ *
+ * // Component B joins:
+ * const { send: sendB } = chat.join((msg) => {
+ *   console.log("B received:", msg);
+ * });
+ *
+ * sendA("hello from A"); // only B receives
+ * sendB("hello from B"); // only A receives
+ * leaveA();              // A leaves the channel
+ * ```
+ */
+export declare const channel: <T = any>() => ChannelType<T>;
+export { type XTabEventType, xTabEvent } from "./xTabEvent";
+//# sourceMappingURL=events.d.ts.map

package/dist/types/lib/Mutables/events/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/events/events.ts"],"names":[],"mappings":"AASA,KAAK,YAAY,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;AAE/C,MAAM,WAAW,SAAS,CAAC,CAAC,GAAG,GAAG;IAChC,WAAW,EAAE,CAAC,EAAE,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,MAAM,IAAI,CAAC;IACjD,OAAO,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,IAAI,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,IAAI,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,KAAK,GAAI,CAAC,GAAG,GAAG,EAAE,OAAO,MAAM,KAAG,SAAS,CAAC,CAAC,CAgBzD,CAAC;AAEF,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,GAAG;IAClC,IAAI,EAAE,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK;QAClC,KAAK,EAAE,MAAM,IAAI,CAAC;QAClB,IAAI,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,IAAI,CAAC;KAC1B,CAAC;IACF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,IAAI,CAAC;CACtB;AAED,KAAK,cAAc,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;AAErE,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,GAAG;IACvC,WAAW,EAAE,CAAC,EAAE,EAAE,cAAc,CAAC,CAAC,CAAC,KAAK,MAAM,IAAI,CAAC;IACnD,OAAO,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,IAAI,CAAC;IAC5B,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,mBAAmB,EAAE,MAAM,IAAI,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,mBAAmB,EAAE,IAAI,CAAC;IAC1B,YAAY,EAAE,IAAI,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,GAAG,GAAG,EAAE,OAAO,MAAM,KAAG,gBAAgB,CAAC,CAAC,CAwEvE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,GAAG,GAAG,OAAK,WAAW,CAAC,CAAC,CAoChD,CAAC;AAEF,OAAO,EAAE,KAAK,aAAa,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/types/lib/Mutables/events/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./events";
+//# sourceMappingURL=index.d.ts.map

package/dist/types/lib/Mutables/events/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/events/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC"}

package/dist/types/lib/Mutables/events/xTabEvent.d.ts

@@ -0,0 +1,61 @@
+import type { EventType } from "./events";
+/**
+ * Extends `EventType<T>` with cross-tab–specific members.
+ * Use `close()` to tear down the underlying `BroadcastChannel` when the event
+ * is no longer needed (e.g. in tests or on app teardown).
+ */
+export interface XTabEventType<T = any> extends EventType<T> {
+    close: () => void;
+    __isXTabEvent___: true;
+}
+/**
+ * Creates a **cross-tab** typed pub/sub event backed by the native
+ * `BroadcastChannel` API.  Satisfies the `EventType<T>` interface, so it
+ * works transparently with `on()` — pass it as a dep just like a regular
+ * `event()`.
+ *
+ * **Key difference vs `event()`:** `trigger()` fires handlers in the
+ * originating tab *and* posts the message to every other open tab sharing the
+ * same `name`.  Handlers in remote tabs are called via the `BroadcastChannel`
+ * `onmessage` callback.
+ *
+ * ---
+ *
+ * ### Members
+ *
+ * - `trigger(data?)` — posts to the `BroadcastChannel` **and** calls all
+ *   local in-memory handlers synchronously, so the originating tab also fires.
+ *   Logs to devtools.
+ *
+ * - `__subscribe(fn)` — registers a local handler and returns an unsubscribe
+ *   function.  When called inside a component, the unsub is automatically
+ *   registered via `registerCleanup` so the handler is removed on unmount.
+ *
+ * - `close()` — closes the underlying `BroadcastChannel`.  Useful in tests or
+ *   on app teardown.  Local in-memory handlers are unaffected; they simply
+ *   stop receiving messages from other tabs.
+ *
+ * ### SSR / Node fallback
+ *
+ * When `BroadcastChannel` is not available (SSR, Node, or old browsers) the
+ * primitive falls back to **in-memory-only** mode: `trigger()` still fires all
+ * local handlers synchronously; `postMessage` and `close()` become no-ops.
+ *
+ * @example
+ * ```ts
+ * const syncTheme = xTabEvent<"light" | "dark">("app:theme");
+ *
+ * // Subscribe in a component (auto-cleaned up on unmount)
+ * syncTheme.__subscribe((theme) => {
+ *   document.body.setAttribute("data-theme", theme);
+ * });
+ *
+ * // Trigger — fires all local handlers AND posts to all other open tabs
+ * syncTheme.trigger("dark");
+ *
+ * // Close the BroadcastChannel when done (e.g. in tests)
+ * syncTheme.close();
+ * ```
+ */
+export declare const xTabEvent: <T = any>(name: string) => XTabEventType<T>;
+//# sourceMappingURL=xTabEvent.d.ts.map

package/dist/types/lib/Mutables/events/xTabEvent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xTabEvent.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/events/xTabEvent.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAI1C;;;;GAIG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,GAAG,CAAE,SAAQ,SAAS,CAAC,CAAC,CAAC;IAC1D,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,gBAAgB,EAAE,IAAI,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,GAAG,GAAG,EAAE,MAAM,MAAM,KAAG,aAAa,CAAC,CAAC,CA2EhE,CAAC"}