mates-devtools 0.1.0-beta.1

package/dist/types/lib/Fetch/Fetch.d.ts

@@ -0,0 +1,168 @@
+import type { AsyncActionReturnType, AsyncFetchOptions } from "../actions/asyncActionTypes";
+import { ZeroPromise } from "../ZeroPromise/zero";
+export { setSSRApiLookup, setSSRRequest } from "../ssr/ssr-bridge";
+export type FetchRequest = Omit<RequestInit, "body"> & {
+    /**
+     * URL for this request.
+     *
+     * - If it starts with `http:` or `https:` it is used as-is (absolute URL),
+     *   ignoring any `host` set on the client/base request.
+     * - Otherwise it is treated as a path and appended to `host`
+     *   (e.g. `host = "https://api.example.com"` + `url = "/users"` →
+     *   `"https://api.example.com/users"`).
+     * - Dynamic segments (`:id`) are substituted from `params`.
+     *
+     * @example
+     * { url: "/users/:id/posts", params: { id: 7, page: 2 } }
+     * // → /users/7/posts?page=2
+     */
+    url?: string;
+    /**
+     * Alias for `url`. When `url` is not provided, `path` is used as the URL
+     * template. Useful for configs that use `{ host, path }` instead of
+     * `{ host, url }`.
+     */
+    path?: string;
+    /**
+     * Origin / base host, e.g. `"https://api.example.com"`.
+     * Used as a prefix when `url` is a relative path.
+     * Defaults to `""` (no host prefix).
+     */
+    host?: string;
+    /**
+     * Route + query-string params — a plain object.
+     * Keys matching a `:token` in `url` are used as path params (via buildPath).
+     * All remaining keys are appended as query-string parameters.
+     */
+    params?: Record<string, any>;
+    /** Request body — plain objects are JSON-serialised automatically. */
+    body?: BodyInit | Record<string, any> | null;
+};
+/**
+ * Convenience type — most call sites just need a URL string; the full
+ * `FetchRequest` object is available for advanced configuration.
+ */
+export type FetchInput = string | FetchRequest;
+export type BeforeInterceptor = (url: string, options: RequestInit) => {
+    url: string;
+    options: RequestInit;
+};
+export type AfterInterceptor = (response: Response) => Response;
+export type ErrorInterceptor = (error: Error) => void;
+/** Build the final URL from a FetchRequest. */
+export declare function buildRequestUrl(request: FetchRequest): string;
+export type FetchBody = BodyInit | Record<string, any> | null;
+export type FetchActionConfig = FetchRequest & AsyncFetchOptions;
+export declare const interceptBefore: (fn: BeforeInterceptor) => () => void;
+export declare const interceptAfter: (fn: AfterInterceptor) => () => void;
+export declare const interceptError: (fn: ErrorInterceptor) => () => void;
+export declare const clearInterceptors: () => void;
+/**
+ * A self-contained HTTP client.
+ *
+ * - Constructor accepts a base `FetchRequest` (host, default headers, etc.)
+ *   that is merged under every call-site request.
+ * - Each instance maintains its own interceptor chain, which runs **before**
+ *   the global interceptors.
+ * - All requests are logged to Mates DevTools when devtools is connected.
+ *
+ * @example
+ * const api = new FetchClient({ host: "https://api.example.com" });
+ * api.interceptBefore((url, opts) => ({
+ *   url,
+ *   options: { ...opts, headers: { ...opts.headers, Authorization: `Bearer ${token}` } },
+ * }));
+ *
+ * const users = await api.Get({ url: "/users", params: { page: 1 } });
+ */
+export declare class FetchClient {
+    private readonly baseRequest;
+    private readonly instanceBeforeFns;
+    private readonly instanceAfterFns;
+    private readonly instanceErrorFns;
+    constructor(baseRequest?: FetchRequest);
+    /** Add a before-interceptor scoped to this instance. Returns an unsubscribe fn. */
+    interceptBefore(fn: BeforeInterceptor): () => void;
+    /** Add an after-interceptor scoped to this instance. Returns an unsubscribe fn. */
+    interceptAfter(fn: AfterInterceptor): () => void;
+    /** Add an error-interceptor scoped to this instance. Returns an unsubscribe fn. */
+    interceptError(fn: ErrorInterceptor): () => void;
+    /** Remove all interceptors scoped to this instance. */
+    clearInterceptors(): void;
+    fetch<T = any>(request: FetchRequest): ZeroPromise<T>;
+    /** Public alias for `fetch` — matches the exported global `Fetch` name. */
+    Fetch<T = any>(request: FetchRequest): ZeroPromise<T>;
+    Get<T = any>(request: FetchRequest): ZeroPromise<T>;
+    Post<T = any>(request: FetchRequest): ZeroPromise<T>;
+    Put<T = any>(request: FetchRequest): ZeroPromise<T>;
+    Patch<T = any>(request: FetchRequest): ZeroPromise<T>;
+    Delete<T = any>(request: FetchRequest): ZeroPromise<T>;
+    /**
+     * Creates an asyncAction that calls this client's Fetch().
+     *
+     * The base config (host, path, method, headers, …) is fixed at creation time.
+     * The returned action accepts a plain `params` object whose keys are used to
+     * fill dynamic path segments (`:id`) and/or appended as query-string params —
+     * exactly as `buildRequestUrl` handles them.
+     *
+     * @example
+     * const loadUser = api.fetchAction({ host: "https://api.example.com", url: "/users/:id" });
+     * loadUser({ id: 7, expand: "posts" });
+     * // → GET https://api.example.com/users/7?expand=posts
+     */
+    fetchAction<T = unknown>(config?: FetchActionConfig): AsyncActionReturnType<(params?: Record<string, any>) => Promise<T>>;
+    /**
+     * Creates an asyncAction that always issues a GET request via this client.
+     *
+     * @example
+     * const loadUsers = api.getAction({ host: "https://api.example.com", url: "/users" });
+     * loadUsers({ page: 2, limit: 20 });
+     */
+    getAction<T = unknown>(config?: FetchActionConfig): AsyncActionReturnType<(params?: Record<string, any>) => Promise<T>>;
+    /**
+     * Creates an asyncAction that always issues a POST request via this client.
+     *
+     * @example
+     * const createUser = api.postAction({ host: "https://api.example.com", url: "/users" });
+     * createUser({ name: "Alice" });
+     */
+    postAction<T = unknown>(config?: FetchActionConfig): AsyncActionReturnType<(params?: Record<string, any>) => Promise<T>>;
+    /**
+     * Creates an asyncAction that always issues a PUT request via this client.
+     *
+     * @example
+     * const replaceUser = api.putAction({ host: "https://api.example.com", url: "/users/:id" });
+     * replaceUser({ id: 7, name: "Bob" });
+     */
+    putAction<T = unknown>(config?: FetchActionConfig): AsyncActionReturnType<(params?: Record<string, any>) => Promise<T>>;
+    /**
+     * Creates an asyncAction that always issues a PATCH request via this client.
+     *
+     * @example
+     * const patchUser = api.patchAction({ host: "https://api.example.com", url: "/users/:id" });
+     * patchUser({ id: 7, status: "inactive" });
+     */
+    patchAction<T = unknown>(config?: FetchActionConfig): AsyncActionReturnType<(params?: Record<string, any>) => Promise<T>>;
+    /**
+     * Creates an asyncAction that always issues a DELETE request via this client.
+     *
+     * @example
+     * const removeUser = api.deleteAction({ host: "https://api.example.com", url: "/users/:id" });
+     * removeUser({ id: 7 });
+     */
+    deleteAction<T = unknown>(config?: FetchActionConfig): AsyncActionReturnType<(params?: Record<string, any>) => Promise<T>>;
+}
+export declare const fetchClient: FetchClient;
+export declare const Fetch: <T = any>(request: FetchInput) => ZeroPromise<T>;
+export declare const Get: <T = any>(request: FetchInput) => ZeroPromise<T>;
+export declare const Post: <T = any>(request: FetchInput) => ZeroPromise<T>;
+export declare const Put: <T = any>(request: FetchInput) => ZeroPromise<T>;
+export declare const Patch: <T = any>(request: FetchInput) => ZeroPromise<T>;
+export declare const Delete: <T = any>(request: FetchInput) => ZeroPromise<T>;
+export declare const fetchAction: <T = unknown>(config?: FetchActionConfig) => AsyncActionReturnType<(params?: Record<string, any>) => Promise<T>>;
+export declare const getAction: <T = unknown>(config?: FetchActionConfig) => AsyncActionReturnType<(params?: Record<string, any>) => Promise<T>>;
+export declare const postAction: <T = unknown>(config?: FetchActionConfig) => AsyncActionReturnType<(params?: Record<string, any>) => Promise<T>>;
+export declare const putAction: <T = unknown>(config?: FetchActionConfig) => AsyncActionReturnType<(params?: Record<string, any>) => Promise<T>>;
+export declare const patchAction: <T = unknown>(config?: FetchActionConfig) => AsyncActionReturnType<(params?: Record<string, any>) => Promise<T>>;
+export declare const deleteAction: <T = unknown>(config?: FetchActionConfig) => AsyncActionReturnType<(params?: Record<string, any>) => Promise<T>>;
+//# sourceMappingURL=Fetch.d.ts.map

package/dist/types/lib/Fetch/Fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Fetch.d.ts","sourceRoot":"","sources":["../../../../../lib/Fetch/Fetch.ts"],"names":[],"mappings":"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"}

package/dist/types/lib/Fetch/index.d.ts

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

package/dist/types/lib/Fetch/index.d.ts.map

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

package/dist/types/lib/Mutables/Extended Atoms/cacheAtom.d.ts

@@ -0,0 +1,156 @@
+import { type AtomConfig, type AtomType } from "../atom/atom";
+/**
+ * A reactive `Map<string, T>` with optional per-entry TTL auto-expiry.
+ *
+ * Extends the base `AtomType` interface (minus `set` and `update`, which are
+ * replaced by the higher-level mutation methods below).  Calling the atom as
+ * a function — `cache()` — returns the underlying `Map<string, T>` and
+ * registers the caller as a reactive subscriber, exactly as a plain atom would.
+ *
+ * @template T  The type of values stored in the cache.
+ *
+ * @example
+ * ```ts
+ * interface User { name: string }
+ *
+ * const userCache = cacheAtom<User>();
+ *
+ * // Permanent entry
+ * userCache.add("u2", { name: "Bob" });
+ *
+ * // Entry that expires after 30 s
+ * userCache.add("u1", { name: "Alice" }, 30_000);
+ *
+ * console.log(userCache.get("u1")); // { name: "Alice" }
+ * console.log(userCache.size);      // 2
+ * console.log(userCache.getAll());  // [{ name: "Alice" }, { name: "Bob" }]
+ *
+ * // Manual eviction
+ * userCache.remove("u2");           // true
+ *
+ * // Replace an entry — existing timer is cancelled automatically
+ * userCache.add("u1", { name: "Alice Updated" }, 60_000);
+ *
+ * // Wipe everything
+ * userCache.clearAll();
+ * ```
+ */
+export type CacheAtomType<T> = Omit<AtomType<Map<string, T>>, "set" | "update"> & {
+    /**
+     * Inserts or replaces an entry in the cache.
+     *
+     * - If `id` already exists any pending expiry timer is cancelled first.
+     * - If `ttl` is a positive number the entry is automatically removed after
+     *   `ttl` milliseconds.
+     * - If `ttl` is `-1` or omitted the entry is permanent until manually
+     *   removed or `clearAll()` is called.
+     *
+     * Notifies all subscribers after the mutation.
+     *
+     * @param id    Unique string key for the entry.
+     * @param value Value to store.
+     * @param ttl   Time-to-live in milliseconds (`> 0`), or `-1` / omitted for
+     *              a permanent entry.
+     */
+    add(id: string, value: T, ttl?: number): void;
+    /**
+     * Returns the cached value for `id`, or `undefined` when absent.
+     *
+     * Registers the calling reactive context as a subscriber.
+     *
+     * @param id  Key to look up.
+     */
+    get(id: string): T | undefined;
+    /**
+     * Removes a single entry from the cache.
+     *
+     * Cancels any pending expiry timer and notifies subscribers.
+     * Returns `false` — without emitting a notification — when `id` is not
+     * present, keeping the behaviour consistent with `Map.prototype.delete`.
+     *
+     * @param id  Key to remove.
+     * @returns   `true` if the entry existed and was removed; `false` otherwise.
+     */
+    remove(id: string): boolean;
+    /**
+     * Returns whether `id` currently exists in the cache.
+     *
+     * Registers the calling reactive context as a subscriber.
+     *
+     * @param id  Key to test.
+     */
+    has(id: string): boolean;
+    /**
+     * Returns a snapshot of all cached values as an ordered array.
+     *
+     * The order reflects the insertion order of the underlying `Map`.
+     * Registers the calling reactive context as a subscriber.
+     */
+    getAll(): T[];
+    /**
+     * Clears the entire cache, cancels every pending expiry timer, and notifies
+     * all subscribers.
+     *
+     * Called automatically when the component that created this atom unmounts.
+     * At module level it must be called manually.
+     */
+    clearAll(): void;
+    /** Reactive number of entries currently held in the cache. */
+    readonly size: number;
+    /** Discriminator tag — always `"cacheAtom"`. */
+    readonly name: "cacheAtom";
+};
+/**
+ * Creates a reactive `Map<string, T>` cache atom with optional per-entry TTL
+ * auto-expiry.
+ *
+ * The returned object is callable (`cache()`) — invoking it returns the
+ * underlying `Map<string, T>` and registers the caller as a reactive subscriber
+ * in exactly the same way a plain `atom` would.
+ *
+ * **Automatic cleanup** — when `cacheAtom` is created inside a component's
+ * outer function, `clearAll()` is registered as a teardown handler via
+ * `registerCleanup`. On component unmount every pending TTL timer is cancelled
+ * and all entries are removed automatically. When created at module level no
+ * automatic cleanup occurs and `clearAll()` must be called manually if needed.
+ *
+ * Internally the factory:
+ * 1. Creates a real `Map<string, T>` (`_map`) as the atom's initial value so
+ *    that `cache()` always returns the same Map reference.
+ * 2. Wraps it in a base `atom` whose identity drives all reactivity.
+ * 3. Captures the original `base.get` **before** overriding `.get` on the
+ *    result object, preventing infinite recursion in subscription-tracking
+ *    calls.
+ * 4. Attaches all extended methods via `(result as any).method = ...`
+ *    following the `paginationAtom` pattern.
+ * 5. Exposes `name`, `size`, `__isAtom___`, and `__version__` as
+ *    `Object.defineProperty` getters following the `mapAtom` pattern.
+ * 6. Calls `registerCleanup(base, clearAll)` — a no-op at module level,
+ *    but hooks into the component host's teardown when called inside a
+ *    component.
+ *
+ * @template T      The type of values stored in the cache.
+ * @param   config  Optional atom configuration forwarded to the base `atom`.
+ * @returns         A fully-reactive {@link CacheAtomType} instance.
+ *
+ * @example
+ * ```ts
+ * // Module level — manual clearAll required
+ * const tokenCache = cacheAtom<string>();
+ * tokenCache.add("jwt", "eyJ...", 15 * 60 * 1000); // expires in 15 min
+ * tokenCache.add("refresh", "abc123");              // permanent
+ *
+ * effect(() => {
+ *   console.log("cache size:", tokenCache.size);    // reactive
+ * });
+ *
+ * // Inside a component — clearAll is called automatically on unmount
+ * const MyComponent = view(() => {
+ *   const recent = cacheAtom<Post>();
+ *   recent.add("p1", post, 60_000);
+ *   // …no manual cleanup needed
+ * });
+ * ```
+ */
+export declare function cacheAtom<T>(config?: AtomConfig): CacheAtomType<T>;
+//# sourceMappingURL=cacheAtom.d.ts.map

package/dist/types/lib/Mutables/Extended Atoms/cacheAtom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cacheAtom.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/Extended Atoms/cacheAtom.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,QAAQ,EAAQ,MAAM,cAAc,CAAC;AAIpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,IAAI,CACjC,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EACxB,KAAK,GAAG,QAAQ,CACjB,GAAG;IACF;;;;;;;;;;;;;;;OAeG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE9C;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;IAE/B;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAE5B;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAEzB;;;;;OAKG;IACH,MAAM,IAAI,CAAC,EAAE,CAAC;IAEd;;;;;;OAMG;IACH,QAAQ,IAAI,IAAI,CAAC;IAEjB,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,gDAAgD;IAChD,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;CAC5B,CAAC;AAIF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,aAAa,CAAC,CAAC,CAAC,CA6KlE"}

package/dist/types/lib/Mutables/Extended Atoms/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./cacheAtom";
+export * from "./paginationAtom";
+export * from "./themeAtom";
+//# sourceMappingURL=index.d.ts.map

package/dist/types/lib/Mutables/Extended Atoms/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/Extended Atoms/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC"}

package/dist/types/lib/Mutables/Extended Atoms/paginationAtom.d.ts

@@ -0,0 +1,32 @@
+import { type AtomConfig, type AtomType } from "../atom/atom";
+export type PaginationAtomType = AtomType<number> & {
+    readonly currentPage: number;
+    next(): void;
+    prev(): void;
+    reset(): void;
+    readonly name: "paginationAtom";
+};
+/**
+ * Creates a reactive pagination atom.
+ *
+ * Inherits the full `AtomType<number>` interface — callable, `.get()`,
+ * `.set()`, `.update()`, `.val`, `.__subscribe()`, `.__version__`,
+ * `.lock()` / `.unlock()`, `.toJSON()` — plus pagination-specific helpers:
+ *
+ * - `currentPage` — alias for the current value.
+ * - `next()`      — increment by 1.
+ * - `prev()`      — decrement by 1 (floors at 1).
+ * - `reset()`     — set back to 1.
+ *
+ * @param initial - Starting page number (default: 1).
+ *
+ * @example
+ * const page = paginationAtom(1);
+ * page.next();        // 2
+ * page.prev();        // 1
+ * page.reset();       // 1
+ * page();             // 1  — callable read
+ * page.currentPage;   // 1
+ */
+export declare const paginationAtom: (initial?: number, config?: AtomConfig) => PaginationAtomType;
+//# sourceMappingURL=paginationAtom.d.ts.map

package/dist/types/lib/Mutables/Extended Atoms/paginationAtom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paginationAtom.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/Extended Atoms/paginationAtom.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,QAAQ,EAAQ,MAAM,cAAc,CAAC;AAIpE,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG;IAClD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,IAAI,IAAI,IAAI,CAAC;IACb,IAAI,IAAI,IAAI,CAAC;IACb,KAAK,IAAI,IAAI,CAAC;IACd,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;CACjC,CAAC;AAIF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,cAAc,GACzB,UAAS,MAAU,EACnB,SAAS,UAAU,KAClB,kBAiCF,CAAC"}

package/dist/types/lib/Mutables/Extended Atoms/themeAtom.d.ts

@@ -0,0 +1,59 @@
+import { type AtomType } from "../atom/atom";
+/** The three possible theme values a user can choose. */
+export type ThemeValue = "light" | "dark" | "auto";
+/**
+ * A reactive theme atom extended with convenience mutators and a pre-resolved
+ * `resolved` getter.
+ *
+ * Inherits the full `AtomType<ThemeValue>` interface — callable, `.get()`,
+ * `.set()`, `.val`, `.__subscribe()`, `.__version__`, etc. — plus
+ * theme-specific helpers:
+ *
+ * - `setToLight()` — force light mode and persist choice.
+ * - `setToDark()`  — force dark mode and persist choice.
+ * - `setToAuto()`  — follow OS preference, removes stored key.
+ * - `toggle()`     — flip between "light" and "dark"; resolves OS preference
+ *                    first if currently "auto"; result is always explicit.
+ * - `resolved`     — the effective theme, always "light" or "dark".
+ */
+export type ThemeAtomType = AtomType<ThemeValue> & {
+    /** Explicitly set theme to "light" and persist to localStorage. */
+    setToLight(): void;
+    /** Explicitly set theme to "dark" and persist to localStorage. */
+    setToDark(): void;
+    /** Follow the OS color-scheme preference. Removes localStorage key. */
+    setToAuto(): void;
+    /**
+     * Toggle between "light" and "dark".
+     * If currently "auto", resolves OS preference first, then flips.
+     * After toggle the theme is always explicit (never "auto").
+     */
+    toggle(): void;
+    /** The resolved theme — always "light" or "dark", never "auto". */
+    readonly resolved: "light" | "dark";
+    readonly name: "themeAtom";
+};
+/**
+ * The singleton reactive theme atom.
+ *
+ * Use directly — it is the atom, not a factory.
+ *
+ * - Reads the initial theme from `localStorage["mates-theme"]`.
+ * - Falls back to the OS color-scheme preference when no value is stored.
+ * - Keeps `<html data-theme="…">` in sync automatically via an internal effect.
+ * - Persists changes to localStorage (removes key for "auto").
+ * - Re-applies the resolved theme when the OS preference changes while in
+ *   "auto" mode, re-notifying all subscribers so derived UIs update.
+ *
+ * @example
+ * import { themeAtom } from "mates";
+ *
+ * themeAtom.setToDark();
+ * themeAtom.toggle();      // → "light"
+ * themeAtom.setToAuto();   // follows OS
+ * themeAtom.resolved;      // "light" | "dark" — never "auto"
+ * themeAtom();             // read current value: "light" | "dark" | "auto"
+ * themeAtom.val;           // same
+ */
+export declare const themeAtom: ThemeAtomType;
+//# sourceMappingURL=themeAtom.d.ts.map

package/dist/types/lib/Mutables/Extended Atoms/themeAtom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"themeAtom.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/Extended Atoms/themeAtom.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAQ,MAAM,cAAc,CAAC;AAUnD,yDAAyD;AACzD,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAEnD;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC,UAAU,CAAC,GAAG;IACjD,mEAAmE;IACnE,UAAU,IAAI,IAAI,CAAC;IACnB,kEAAkE;IAClE,SAAS,IAAI,IAAI,CAAC;IAClB,uEAAuE;IACvE,SAAS,IAAI,IAAI,CAAC;IAClB;;;;OAIG;IACH,MAAM,IAAI,IAAI,CAAC;IACf,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;CAC5B,CAAC;AA6JF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,SAAS,EAAE,aAAgC,CAAC"}

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

@@ -0,0 +1,148 @@
+type Subscriber = () => void;
+type Updater<T> = (prev: T) => T;
+type UpdateFn<T> = (draft: T) => void;
+export type AtomConfig = {
+    /** Skip the restricted-context guard so the atom can be created inside templates, effects, etc. */
+    skipRestrictedContextCheck?: boolean;
+};
+export type AtomType<T> = {
+    (): T;
+    get(): T;
+    set(value: T | Updater<T>, silently?: boolean): void;
+    update(fn: UpdateFn<T>, silently?: boolean): void;
+    __subscribe(fn: Subscriber): () => void;
+    toJSON(): string;
+    /** Writable so extended atoms can stamp their own name (e.g. "iAtom"). */
+    name: string;
+    readonly val: T;
+    readonly __version__: number;
+    readonly __isAtom___: true;
+    readonly __id__: number;
+    /** Set to true to suppress devtools logging for this atom's set/update calls. */
+    skipDevToolsLog?: boolean;
+};
+/**
+ * Create a reactive atom.
+ *
+ * The core reactive primitive in mates — a single callable function object
+ * with `get`, `set`, `update`, `val`, `__subscribe`, `__version__`,
+ * `__id__`, `toJSON`, and `name`.
+ *
+ * Callable as `count()` as shorthand for `count.get()`.
+ * Both `get()` and the `val` getter participate in view subscription and
+ * read-tracking so components re-render automatically.
+ *
+ * For lock/unlock use `superAtom()`.
+ *
+ * When a **function** is passed as `initial`, the atom is treated as a
+ * derived/memoised atom. The function is called via `memo()` and the
+ * resulting reactive atom is returned. In this mode `config` is ignored.
+ *
+ * @param initial - The initial value for the atom, **or** a derive function
+ *   `() => T` to create a memoised/derived atom.
+ * @param config  - Optional configuration object (ignored for derived atoms).
+ * @param config.skipRestrictedContextCheck - When `true`, bypasses the guard
+ *   that normally prevents atom creation inside templates, effects, or memos.
+ *   Useful for directives and other advanced patterns that intentionally
+ *   create atoms from within a template function. Defaults to `false`.
+ *
+ * @example
+ * const count = atom(0);
+ * count.set(1);
+ * count.set(n => n + 1);
+ * count();          // 2
+ * count.val;        // 2
+ * count.update(d => { d.x = 1 }); // for objects
+ * count.toJSON();   // "2"
+ * count.name;       // "atom"
+ * count.__id__;     // unique incrementing integer
+ *
+ * // Derived / memoised atom — re-computes whenever its dependencies change:
+ * const double = atom(() => count() * 2);
+ * double();         // 4
+ *
+ * // Inside a directive or other restricted context:
+ * const flag = atom(false, { skipRestrictedContextCheck: true });
+ */
+export declare function atom<T>(initial: (() => T) | T, config?: AtomConfig): AtomType<T>;
+export type IAtomType<T> = {
+    (): T;
+    get(): T;
+    set(value: T | ((prev: T) => T), silently?: boolean): void;
+    __subscribe(fn: () => void): () => void;
+    toJSON(): string;
+    name: string;
+    readonly val: T;
+    readonly __version__: number;
+    readonly __isAtom___: true;
+    readonly __id__: number;
+};
+/**
+ * Create a deep-frozen reactive atom.
+ *
+ * Every value written via `set()` is automatically deep-frozen, preventing
+ * accidental mutation. `update()` is removed — use `set()` with a new object.
+ *
+ * All other `atom()` capabilities are preserved: callable, `get`, `val`,
+ * `__subscribe`, `__version__`, `__id__`, `toJSON`.
+ *
+ * For lock/unlock use `superAtom({ freeze: true })`.
+ *
+ * @param initial - The initial value (will be deep-frozen).
+ * @param config  - Optional configuration object.
+ * @param config.skipRestrictedContextCheck - When `true`, bypasses the guard
+ *   that normally prevents atom creation inside templates, effects, or memos.
+ *   Defaults to `false`.
+ *
+ * @example
+ * const cfg = iAtom({ api: "https://..." });
+ * cfg.set({ api: "https://v2..." });
+ * cfg.set(prev => ({ ...prev, api: "https://v3..." }));
+ * Object.isFrozen(cfg()); // true
+ */
+export declare function iAtom<T>(initial: T, config?: AtomConfig): IAtomType<T>;
+export type SuperAtomOptions = {
+    /** deepFreeze every value written to this atom. */
+    freeze?: boolean;
+    /** Skip the restricted-context guard so the atom can be created inside templates, effects, etc. */
+    skipRestrictedContextCheck?: boolean;
+};
+export type SuperAtomType<T> = AtomType<T> & {
+    lock(passcode?: string): void;
+    unlock(passcode?: string): void;
+    reset(): void;
+    freeze(): void;
+    readonly name: string;
+};
+/**
+ * Create a full-featured reactive atom.
+ *
+ * Extends `atom()` with:
+ * - `lock(passcode?)` / `unlock(passcode?)` — prevent/allow mutations.
+ * - `reset()`           — restore the initial value and notify subscribers.
+ * - `freeze()`          — deepFreeze the current value in place.
+ * - `{ freeze: true }`  — deepFreeze every value on set (like `iAtom` but
+ *                          with lock/unlock and update throws a helpful error).
+ *
+ * @param initial - The initial value.
+ * @param options - Optional configuration object.
+ * @param options.freeze - When `true`, deep-freezes every value on set.
+ * @param options.skipRestrictedContextCheck - When `true`, bypasses the guard
+ *   that normally prevents atom creation inside templates, effects, or memos.
+ *   Defaults to `false`.
+ *
+ * @example
+ * const config = superAtom({ theme: "light" });
+ * config.lock();
+ * config.set({ theme: "dark" }); // silently ignored
+ * config.unlock();
+ * config.set({ theme: "dark" }); // works
+ * config.reset();                // back to { theme: "light" }
+ *
+ * // Immutable variant with lock:
+ * const cfg = superAtom({ api: "https://..." }, { freeze: true });
+ * cfg.lock("secret");
+ */
+export declare function superAtom<T>(initial: T, options?: SuperAtomOptions): SuperAtomType<T>;
+export { deepFreeze as df } from "../../Utils/deepFreeze";
+//# sourceMappingURL=atom.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"atom.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/atom/atom.ts"],"names":[],"mappings":"AAoBA,KAAK,UAAU,GAAG,MAAM,IAAI,CAAC;AAC7B,KAAK,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC;AACjC,KAAK,QAAQ,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;AAEtC,MAAM,MAAM,UAAU,GAAG;IACvB,mGAAmG;IACnG,0BAA0B,CAAC,EAAE,OAAO,CAAC;CACtC,CAAC;AAcF,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;IACxB,IAAI,CAAC,CAAC;IACN,GAAG,IAAI,CAAC,CAAC;IACT,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACrD,MAAM,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAClD,WAAW,CAAC,EAAE,EAAE,UAAU,GAAG,MAAM,IAAI,CAAC;IACxC,MAAM,IAAI,MAAM,CAAC;IACjB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC;IAChB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iFAAiF;IACjF,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,IAAI,CAAC,CAAC,EACpB,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,EACtB,MAAM,CAAC,EAAE,UAAU,GAClB,QAAQ,CAAC,CAAC,CAAC,CA2Gb;AAUD,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IACzB,IAAI,CAAC,CAAC;IACN,GAAG,IAAI,CAAC,CAAC;IACT,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC3D,WAAW,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IACxC,MAAM,IAAI,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC;IAChB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC,CAAC,CAAC,CA8BtE;AAaD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,mDAAmD;IACnD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,mGAAmG;IACnG,0BAA0B,CAAC,EAAE,OAAO,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,GAAG;IAC3C,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,MAAM,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,KAAK,IAAI,IAAI,CAAC;IACd,MAAM,IAAI,IAAI,CAAC;IACf,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,SAAS,CAAC,CAAC,EACzB,OAAO,EAAE,CAAC,EACV,OAAO,GAAE,gBAAqB,GAC7B,aAAa,CAAC,CAAC,CAAC,CAkFlB;AA4BD,OAAO,EAAE,UAAU,IAAI,EAAE,EAAE,MAAM,wBAAwB,CAAC"}

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

@@ -0,0 +1,43 @@
+import { type AtomConfig, type AtomType } from "./atom";
+type TimingFunction = <T extends (...args: any[]) => any>(fn: T, delay: number) => T & {
+    cancel: () => void;
+    flush?: () => void;
+};
+/**
+ * Internal factory used by `debouncedAtom` and `throttledAtom` to create a
+ * timing-controlled reactive atom.
+ *
+ * **When `initialAtomOrState` is a plain value:**
+ * A new atom is created with that value. Its `set` and `update` methods are
+ * replaced with timing-wrapped versions so every write is gated by `timingFn`.
+ *
+ * **When `initialAtomOrState` is already an atom (source atom):**
+ * A new atom is created that mirrors the source atom's current value. The new
+ * atom's `set` and `update` are timing-wrapped, and a subscription to the
+ * source atom is established so the derived atom stays in sync whenever the
+ * source changes.
+ *
+ * In both cases, `registerCleanup` is called on the new atom so any pending
+ * timer is cancelled automatically when the atom is disposed.
+ *
+ * @param initialAtomOrState - Either a plain initial value or a source `AtomType<T>` to mirror.
+ * @param delay - The timing window in milliseconds passed to `timingFn`.
+ * @param timingFn - A timing higher-order function (`debounce` or `throttle`) that
+ *   wraps a function and returns it decorated with a `.cancel()` method.
+ * @param config - Optional atom configuration forwarded to the underlying `atom()` call.
+ * @returns A new `AtomType<T>` whose writes are gated by `timingFn`.
+ *
+ * @example
+ * // Plain value — writes are debounced/throttled directly:
+ * const a = createTimedAtom("", 300, debounce);
+ * a.set("hello"); // fires after 300 ms of inactivity
+ *
+ * @example
+ * // Source atom — the new atom mirrors the source with timing applied:
+ * const source = atom(0);
+ * const timed = createTimedAtom(source, 100, throttle);
+ * source.set(42); // timed will reflect 42, but at most once per 100 ms
+ */
+export declare const createTimedAtom: <T>(initialAtomOrState: T | AtomType<T>, delay: number, timingFn: TimingFunction, config?: AtomConfig) => AtomType<T>;
+export {};
+//# sourceMappingURL=createTimedAtom.d.ts.map