ink-cartridge 3.6.1

package/dist/storage/storage.js

@@ -0,0 +1,236 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/**
+ * A key-value storage station backed by a single JSON file.
+ *
+ * Each instance manages one JSON file on disk. All read/write operations
+ * are asynchronous and serialised internally — concurrent callers never
+ * interleave. The file is loaded lazily on the first access, and writes
+ * use atomic rename (write to `.tmp` then rename) to prevent data
+ * corruption from partial writes or crashes.
+ *
+ * Instances are created via {@link createStorage}, not directly.
+ */
+export class Storage {
+    options;
+    data = null;
+    pending = Promise.resolve();
+    filePath;
+    constructor(options) {
+        this.options = {
+            dir: options?.dir ?? './data',
+            file: options?.file ?? 'config.json',
+            flush: options?.flush ?? true,
+        };
+        this.filePath = path.resolve(this.options.dir, this.options.file);
+        this.ensureDir();
+    }
+    /**
+     * Typed write methods.
+     *
+     * Each method writes a value of the corresponding type to the given key.
+     * The write is serialised: it waits for any pending writes to complete,
+     * then atomically persists the updated JSON to disk.
+     *
+     * `any` is the untyped escape hatch — it accepts any value and performs
+     * no type-checking on subsequent reads unless you use a typed read method.
+     */
+    write = {
+        /** Persist a numeric value under `key`. */
+        num: (key, value) => this.setValue(key, value),
+        /** Persist a string value under `key`. */
+        str: (key, value) => this.setValue(key, value),
+        /** Persist a boolean value under `key`. */
+        b: (key, value) => this.setValue(key, value),
+        /** Persist a plain object under `key`. */
+        obj: (key, value) => this.setValue(key, value),
+        /** Persist an array under `key`. */
+        arr: (key, value) => this.setValue(key, value),
+        /** Persist any value under `key`. No type constraint. */
+        any: (key, value) => this.setValue(key, value),
+        /** Persist any value under `key`. Symmetric alias for `any`. */
+        schema: (key, value) => this.setValue(key, value),
+    };
+    /**
+     * Typed read methods.
+     *
+     * Each method reads the value at `key` and validates that it matches the
+     * expected type. If the key is missing or the stored value has a different
+     * type, `defaultValue` is returned **and the file is repaired** so that
+     * subsequent reads hit the correct value.
+     */
+    read = {
+        /** Read a number. Returns `defaultValue` if missing or wrong type. */
+        num: (key, defaultValue) => this.getValue(key, defaultValue, 'number'),
+        /** Read a string. Returns `defaultValue` if missing or wrong type. */
+        str: (key, defaultValue) => this.getValue(key, defaultValue, 'string'),
+        /** Read a boolean. Returns `defaultValue` if missing or wrong type. */
+        b: (key, defaultValue) => this.getValue(key, defaultValue, 'boolean'),
+        /** Read a plain object (generic). Returns `defaultValue` if missing or wrong type. */
+        obj: (key, defaultValue) => this.getValue(key, defaultValue, 'object'),
+        /** Read an array (generic). Returns `defaultValue` if missing or wrong type. */
+        arr: (key, defaultValue) => this.getValue(key, defaultValue, 'array'),
+        /** Read any value. Returns `defaultValue` if missing. No type validation. */
+        any: (key, defaultValue) => this.getValue(key, defaultValue, 'any'),
+        /** Read a value validated against a zod schema. Auto-repairs on parse failure. */
+        schema: (key, schema, defaultValue) => this.getValueWithSchema(key, schema, defaultValue),
+    };
+    /**
+     * Check whether a key exists in the store.
+     *
+     * @returns `true` if the key has an entry (even if its value is `null`
+     *          or `undefined` — it checks own-property presence).
+     */
+    async has(key) {
+        await this.ensureLoaded();
+        return Object.prototype.hasOwnProperty.call(this.data, key);
+    }
+    /**
+     * Remove a key and its value from the store.
+     *
+     * If the key does not exist this is a no-op (no error thrown).
+     */
+    async delete(key) {
+        await this.ensureLoaded();
+        if (Object.prototype.hasOwnProperty.call(this.data, key)) {
+            delete this.data[key];
+            await this.flush();
+        }
+    }
+    /**
+     * Remove all keys from the store, resetting it to an empty object.
+     */
+    async clear() {
+        this.data = {};
+        await this.flush();
+    }
+    /**
+     * Return a shallow copy of the entire raw data object.
+     *
+     * Modifications to the returned object do **not** affect the store
+     * (use the write methods to persist changes).
+     */
+    async getAll() {
+        await this.ensureLoaded();
+        return { ...this.data };
+    }
+    ensureDir() {
+        fs.mkdirSync(this.options.dir, { recursive: true });
+    }
+    /**
+     * Serialise access so concurrent callers never interleave.
+     *
+     * Each task is chained onto `this.pending` using `.then(task, task)`.
+     * The second argument ensures that even if a previous task rejects,
+     * the next task still runs (the chain is never broken).
+     */
+    enqueue(task) {
+        this.pending = this.pending.then(task, task);
+        return this.pending;
+    }
+    setValue(key, value) {
+        return this.enqueue(async () => {
+            await this.ensureLoaded();
+            this.data[key] = value;
+            await this.flush();
+        });
+    }
+    /**
+     * Read a value with type validation and automatic repair.
+     *
+     * If the key is missing the default is written to disk so that
+     * subsequent reads return it directly. If the stored value has a
+     * different type than expected, the default replaces it on disk.
+     */
+    async getValue(key, defaultValue, expectedType) {
+        await this.ensureLoaded();
+        const stored = this.data[key];
+        if (stored === undefined) {
+            this.data[key] = defaultValue;
+            await this.flush();
+            return defaultValue;
+        }
+        let valid = false;
+        if (expectedType === 'number')
+            valid = typeof stored === 'number';
+        else if (expectedType === 'string')
+            valid = typeof stored === 'string';
+        else if (expectedType === 'boolean')
+            valid = typeof stored === 'boolean';
+        else if (expectedType === 'array')
+            valid = Array.isArray(stored);
+        else if (expectedType === 'object')
+            valid = typeof stored === 'object' && stored !== null && !Array.isArray(stored);
+        else
+            valid = true;
+        if (!valid) {
+            this.data[key] = defaultValue;
+            await this.flush();
+            return defaultValue;
+        }
+        return stored;
+    }
+    /**
+     * Read a value and validate it against a zod schema.
+     *
+     * On success the parsed value is returned (including any transforms
+     * or coercions the schema applies). On failure — missing key or
+     * schema parse error — `defaultValue` is written to disk and returned.
+     */
+    async getValueWithSchema(key, schema, defaultValue) {
+        await this.ensureLoaded();
+        const stored = this.data[key];
+        if (stored === undefined) {
+            this.data[key] = defaultValue;
+            await this.flush();
+            return defaultValue;
+        }
+        const result = schema.safeParse(stored);
+        if (result.success) {
+            return result.data;
+        }
+        this.data[key] = defaultValue;
+        await this.flush();
+        return defaultValue;
+    }
+    /**
+     * Load data from disk on first access (lazy initialisation).
+     *
+     * Once loaded the data stays in memory for the lifetime of the
+     * instance. File-not-found and corrupt-JSON errors are silently
+     * swallowed — in both cases we start with an empty store.
+     */
+    async ensureLoaded() {
+        if (this.data !== null)
+            return;
+        try {
+            const raw = fs.readFileSync(this.filePath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            this.data =
+                typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+                    ? parsed
+                    : {};
+        }
+        catch {
+            this.data = {};
+        }
+    }
+    /**
+     * Atomically persist the in-memory data to disk.
+     *
+     * Writes to a `.tmp` file first, then renames it over the target
+     * file. This guarantees that the on-disk file is always either the
+     * complete previous version or the complete new version — never a
+     * partially-written mess.
+     *
+     * No-op when `options.flush` is `false`.
+     */
+    async flush() {
+        if (!this.options.flush)
+            return;
+        const tmpPath = this.filePath + '.tmp';
+        const content = JSON.stringify(this.data, null, 2);
+        fs.writeFileSync(tmpPath, content, 'utf-8');
+        fs.renameSync(tmpPath, this.filePath);
+    }
+}

package/dist/storage/types.d.ts

@@ -0,0 +1,145 @@
+import type { ZodType } from 'zod';
+/**
+ * Configuration for {@link createStorage}.
+ *
+ * All properties are optional — sensible defaults are provided so that
+ * calling `createStorage()` with no arguments just works.
+ */
+export interface StorageOptions {
+    /**
+     * Directory where the JSON file lives.
+     *
+     * Relative paths are resolved against `process.cwd()`.
+     * The directory (and any missing parents) are created automatically
+     * on construction via `fs.mkdirSync(dir, { recursive: true })`.
+     *
+     * @default './data'
+     */
+    dir?: string;
+    /**
+     * Name of the JSON file backing this storage station.
+     *
+     * @default 'config.json'
+     */
+    file?: string;
+    /**
+     * Whether to write changes to disk immediately after each operation.
+     *
+     * When `false`, in-memory mutations are not persisted until you
+     * manually trigger a flush (or set this back to `true` on a subsequent
+     * write). Useful for batch writes where you want to avoid multiple
+     * disk I/O round-trips.
+     *
+     * @default true
+     */
+    flush?: boolean;
+}
+/**
+ * Resolved storage configuration with every default filled in.
+ *
+ * Internal use only — you never need to construct this manually.
+ */
+export interface ResolvedStorageOptions {
+    dir: string;
+    file: string;
+    flush: boolean;
+}
+/**
+ * The public API returned by {@link createStorage}.
+ *
+ * Provides typed read/write accessors, key management helpers, and
+ * a method to dump the entire store. All methods are async and
+ * serialised internally — callers never need to worry about concurrent
+ * access to the same file.
+ */
+export interface StorageAPI {
+    /**
+     * Typed write methods.
+     *
+     * Each method persists a value of the corresponding type.
+     * Writes are serialised: calling `write.num('a', 1)` followed
+     * immediately by `write.num('b', 2)` will reliably write both keys
+     * in order.
+     */
+    write: {
+        /** Write a numeric value. */
+        num(key: string, value: number): Promise<void>;
+        /** Write a string value. */
+        str(key: string, value: string): Promise<void>;
+        /** Write a boolean value. */
+        b(key: string, value: boolean): Promise<void>;
+        /** Write a plain object (generic — preserves the type for reads). */
+        obj<T extends object>(key: string, value: T): Promise<void>;
+        /** Write an array (generic — preserves the element type for reads). */
+        arr<T>(key: string, value: T[]): Promise<void>;
+        /** Write any value. No type constraint; use with `read.any`. */
+        any(key: string, value: unknown): Promise<void>;
+        /** Write any value (alias for `any` — kept symmetric with `read.schema`). */
+        schema<T>(key: string, value: T): Promise<void>;
+    };
+    /**
+     * Typed read methods.
+     *
+     * Each method validates the stored value against the expected type.
+     * If the key is missing or the type is wrong, `defaultValue` is
+     * returned and the file is automatically repaired.
+     */
+    read: {
+        /** Read a number. Returns `defaultValue` on missing key or type mismatch. */
+        num(key: string, defaultValue: number): Promise<number>;
+        /** Read a string. Returns `defaultValue` on missing key or type mismatch. */
+        str(key: string, defaultValue: string): Promise<string>;
+        /** Read a boolean. Returns `defaultValue` on missing key or type mismatch. */
+        b(key: string, defaultValue: boolean): Promise<boolean>;
+        /** Read a plain object. Returns `defaultValue` on missing key or type mismatch. */
+        obj<T extends object>(key: string, defaultValue: T): Promise<T>;
+        /** Read an array. Returns `defaultValue` on missing key or type mismatch. */
+        arr<T>(key: string, defaultValue: T[]): Promise<T[]>;
+        /** Read any value. Returns `defaultValue` on missing key (no type validation). */
+        any<T>(key: string, defaultValue: T): Promise<T>;
+        /**
+         * Read a value validated against a zod schema.
+         *
+         * On success the parsed value is returned (including any zod transforms
+         * or coercions applied by the schema). On failure — missing key, schema
+         * parse error, or wrong shape — `defaultValue` is returned and the file
+         * is automatically repaired.
+         *
+         * @param key          The key to read.
+         * @param schema       A zod schema to validate the stored value against.
+         * @param defaultValue Fallback value used when validation fails.
+         */
+        schema<T>(key: string, schema: ZodType<T>, defaultValue: T): Promise<T>;
+    };
+    /**
+     * Check whether a key exists in the store.
+     *
+     * @returns `true` if the key has an own-property entry, even if
+     *          its value is `null` or `undefined`.
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Remove a key and its value.
+     *
+     * No-op when the key does not exist.
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Remove all keys, resetting the store to an empty object.
+     */
+    clear(): Promise<void>;
+    /**
+     * Return a shallow copy of the entire data object.
+     *
+     * Changes to the returned object are **not** persisted — use the
+     * write methods for that.
+     */
+    getAll(): Promise<Record<string, unknown>>;
+}
+/**
+ * Internal data store — a flat key-value map serialised as JSON.
+ *
+ * The top-level JSON structure is always an object. Arrays and
+ * primitives at the top level are rejected on load (treated as corrupt).
+ */
+export type StoreData = Record<string, unknown>;

package/dist/storage/types.js

@@ -0,0 +1 @@
+export {};

package/dist/theme/context.d.ts

@@ -0,0 +1,7 @@
+import type { ThemeContextValue } from './types.js';
+/**
+ * Internal React context for the theme system.
+ * Consumers should use the {@link useTheme} hook instead of accessing this
+ * context directly.
+ */
+export declare const ThemeContext: import("react").Context<ThemeContextValue | null>;

package/dist/theme/context.js

@@ -0,0 +1,7 @@
+import { createContext } from 'react';
+/**
+ * Internal React context for the theme system.
+ * Consumers should use the {@link useTheme} hook instead of accessing this
+ * context directly.
+ */
+export const ThemeContext = createContext(null);

package/dist/theme/hook.d.ts

@@ -0,0 +1,11 @@
+import type { ThemeContextValue } from './types.js';
+/**
+ * Access the theme API from within a component tree wrapped by
+ * {@link ThemeProvider}.
+ *
+ * Returns `{ color, style, themeId, themes, setTheme, mergeTheme }`.
+ *
+ * Must be used inside `<ThemeProvider>`. Throws with a clear error
+ * message if no provider is found in the component tree.
+ */
+export declare function useTheme(): ThemeContextValue;

package/dist/theme/hook.js

@@ -0,0 +1,18 @@
+import { useContext } from 'react';
+import { ThemeContext } from './context.js';
+/**
+ * Access the theme API from within a component tree wrapped by
+ * {@link ThemeProvider}.
+ *
+ * Returns `{ color, style, themeId, themes, setTheme, mergeTheme }`.
+ *
+ * Must be used inside `<ThemeProvider>`. Throws with a clear error
+ * message if no provider is found in the component tree.
+ */
+export function useTheme() {
+    const ctx = useContext(ThemeContext);
+    if (!ctx) {
+        throw new Error('[Ink-Cartridge] useTheme() must be called inside a <ThemeProvider>.');
+    }
+    return ctx;
+}

package/dist/theme/index.d.ts

@@ -0,0 +1,4 @@
+export { ThemeProvider } from './provider.js';
+export type { ThemeProviderProps } from './provider.js';
+export { useTheme } from './hook.js';
+export type { ThemeDefinition, ThemeContextValue } from './types.js';

package/dist/theme/index.js

@@ -0,0 +1,2 @@
+export { ThemeProvider } from './provider.js';
+export { useTheme } from './hook.js';

package/dist/theme/provider.d.ts

@@ -0,0 +1,18 @@
+import React from 'react';
+import type { ThemeDefinition } from './types.js';
+export interface ThemeProviderProps {
+    children: React.ReactNode;
+    themes?: ThemeDefinition[];
+    path?: string;
+    defaultTheme?: string;
+}
+/**
+ * Context provider for theming.
+ *
+ * Loads theme definitions either from a directory of `{id}.json` files
+ * (via the `path` prop) or from pre-built inline objects (via `themes`).
+ *
+ * Descendant components can use the {@link useTheme} hook to access
+ * `color()` and `style()` functions, and `setTheme()` to switch themes.
+ */
+export declare function ThemeProvider({ children, themes: inlineThemes, path, defaultTheme, }: ThemeProviderProps): React.JSX.Element;