state-sync-log 0.9.0

package/dist/types/ClientId.d.ts

@@ -0,0 +1 @@
+export type ClientId = string;

package/dist/types/SortedTxEntry.d.ts

@@ -0,0 +1,44 @@
+import { TxRecord } from './TxRecord';
+import { TxTimestamp, TxTimestampKey } from './txTimestamp';
+import type * as Y from "yjs";
+/**
+ * A cached tx entry with lazy parsing and optional tx caching.
+ * The timestamp is parsed on first access and cached.
+ * The tx record can be fetched lazily and cached.
+ */
+export declare class SortedTxEntry {
+    readonly txTimestampKey: TxTimestampKey;
+    private readonly _yTx;
+    private _txTimestamp?;
+    private _originalTxTimestampKey?;
+    private _originalTxTimestamp?;
+    private _txRecord?;
+    constructor(txTimestampKey: TxTimestampKey, _yTx: Y.Map<TxRecord>);
+    /**
+     * Gets the parsed timestamp, lazily parsing and caching on first access.
+     */
+    get txTimestamp(): TxTimestamp;
+    /**
+     * Gets the original tx timestamp key, lazily and caching on first access.
+     */
+    get originalTxTimestampKey(): TxTimestampKey | null;
+    /**
+     * Gets the parsed original tx timestamp, lazily parsing and caching on first access.
+     */
+    get originalTxTimestamp(): TxTimestamp | null;
+    /**
+     * Gets the logical (deduplicated) tx timestamp key.
+     * This is the original tx key if it exists, otherwise the physical key.
+     */
+    get dedupTxTimestampKey(): TxTimestampKey;
+    /**
+     * Gets the logical (deduplicated) parsed tx timestamp.
+     * This is the original tx timestamp if it exists, otherwise the physical timestamp.
+     */
+    get dedupTxTimestamp(): TxTimestamp;
+    /**
+     * Gets the tx record, lazily fetching and caching on first access.
+     * Returns undefined if the tx doesn't exist.
+     */
+    get txRecord(): TxRecord;
+}

package/dist/types/StateCalculator.d.ts

@@ -0,0 +1,141 @@
+import { CheckpointRecord, ClientWatermarks } from './checkpoints';
+import { JSONObject } from './json';
+import { Op, ValidateFn } from './operations';
+import { SortedTxEntry } from './SortedTxEntry';
+import { TxRecord } from './TxRecord';
+import { TxTimestamp, TxTimestampKey } from './txTimestamp';
+import type * as Y from "yjs";
+/**
+ * Checks if a transaction is covered by the checkpoint watermarks.
+ */
+export declare function isTransactionInCheckpoint(ts: TxTimestamp, watermarks: ClientWatermarks): boolean;
+/**
+ * StateCalculator encapsulates the sorted transaction cache and state calculation logic.
+ *
+ * It maintains:
+ * - A sorted array of transaction entries
+ * - A map for O(1) lookup
+ * - A tracking index indicating up to which tx the state has been calculated
+ * - The cached calculated state
+ * - The base checkpoint
+ *
+ * The tracking index is invalidated (set to null) when:
+ * - A transaction is inserted before the already-calculated slice
+ * - A transaction is deleted from the already-calculated slice
+ * - The base checkpoint changes
+ */
+export declare class StateCalculator {
+    /** Sorted tx cache (ALL active/future txs, kept sorted by timestamp) */
+    private sortedTxs;
+    /** O(1) existence check and lookup */
+    private sortedTxsMap;
+    /**
+     * Index of the last transaction applied to cachedState.
+     * - null: state needs full recalculation from checkpoint
+     * - -1: no transactions have been applied yet (state === checkpoint state)
+     * - >= 0: transactions up to and including this index have been applied
+     */
+    private lastAppliedIndex;
+    /** The cached calculated state */
+    private cachedState;
+    /** The base checkpoint to calculate state from */
+    private baseCheckpoint;
+    /**
+     * Applied dedup keys - tracks which LOGICAL txs have been applied.
+     * This is the originalTxKey (or physical key if no original) for each applied tx.
+     * Used to properly deduplicate re-emits.
+     */
+    private appliedTxKeys;
+    /** Max clock seen from any transaction (for Lamport clock updates) */
+    private maxSeenClock;
+    /** Validation function (optional) */
+    private validateFn?;
+    constructor(validateFn?: ValidateFn<JSONObject>);
+    /**
+     * Sets the base checkpoint. Invalidates cached state if checkpoint changed.
+     * @returns true if the checkpoint changed
+     */
+    setBaseCheckpoint(checkpoint: CheckpointRecord | null): boolean;
+    /**
+     * Gets the current base checkpoint.
+     */
+    getBaseCheckpoint(): CheckpointRecord | null;
+    /**
+     * Clears all transactions and rebuilds from yTx map.
+     * This is used when the checkpoint changes and we need a fresh start.
+     */
+    rebuildFromYjs(yTx: Y.Map<TxRecord>): void;
+    /**
+     * Inserts a transaction into the sorted cache.
+     * Invalidates cached state if the transaction was inserted before the calculated slice.
+     *
+     * @returns true if this caused invalidation (out-of-order insert)
+     */
+    insertTx(key: TxTimestampKey, yTx: Y.Map<TxRecord>): boolean;
+    /**
+     * Removes multiple transactions from the sorted cache.
+     * @returns the number of keys that were actually removed
+     */
+    removeTxs(keys: readonly TxTimestampKey[]): number;
+    /**
+     * Checks if a transaction key exists in the cache.
+     */
+    hasTx(key: TxTimestampKey): boolean;
+    /**
+     * Gets a transaction entry by key.
+     */
+    getTx(key: TxTimestampKey): SortedTxEntry | undefined;
+    /**
+     * Gets all sorted transaction entries.
+     */
+    getSortedTxs(): readonly SortedTxEntry[];
+    /**
+     * Gets the number of transactions in the cache.
+     */
+    get txCount(): number;
+    /**
+     * Returns true if the state needs full recalculation.
+     */
+    needsFullRecalculation(): boolean;
+    /**
+     * Invalidates the cached state, forcing a full recalculation on next calculateState().
+     * Note: cachedState is kept so computeReconcileOps can diff old vs new state.
+     */
+    invalidate(): void;
+    /**
+     * Calculates and returns the current state, along with a lazy getter for ops that changed from the previous state.
+     *
+     * - If lastAppliedIndex is null: full recalculation from checkpoint
+     * - If lastAppliedIndex >= -1: incremental apply from lastAppliedIndex + 1
+     */
+    calculateState(): {
+        state: JSONObject;
+        getAppliedOps: () => readonly Op[];
+    };
+    /**
+     * Full recalculation of state from the base checkpoint.
+     */
+    private fullRecalculation;
+    /**
+     * Incremental apply of transactions from lastAppliedIndex + 1.
+     * @param returnOps If true, collects applied transactions (to lazy compute ops). If false, skips collection.
+     */
+    private incrementalApply;
+    /**
+     * Gets the max seen clock (for Lamport clock updates).
+     */
+    getMaxSeenClock(): number;
+    /**
+     * Gets the current cached state without recalculating.
+     * Returns null if state has never been calculated.
+     */
+    getCachedState(): JSONObject | null;
+    /**
+     * Gets the last applied timestamp.
+     */
+    getLastAppliedTs(): TxTimestamp | null;
+    /**
+     * Gets the last applied index (for debugging/tracking).
+     */
+    getLastAppliedIndex(): number | null;
+}

package/dist/types/TxRecord.d.ts

@@ -0,0 +1,14 @@
+import { Op } from './operations';
+import { TxTimestampKey } from './txTimestamp';
+/**
+ * The immutable record stored in the Log.
+ */
+export type TxRecord = {
+    ops: readonly Op[];
+    /**
+     * If this is a re-emit of a missed transaction, this field holds the
+     * ORIGINAL key. Used for deduplication to prevent applying the same logical
+     * action twice.
+     */
+    originalTxKey?: TxTimestampKey;
+};

package/dist/types/checkpointUtils.d.ts

@@ -0,0 +1,15 @@
+import { CheckpointRecord } from './checkpoints';
+import * as Y from "yjs";
+/**
+ * Determines the finalized epoch and its canonical checkpoint in a single pass.
+ *
+ * Policy A: The finalized epoch is the most recent epoch with a checkpoint.
+ * Canonical checkpoint: The checkpoint with highest txCount for that epoch
+ * (tie-break: lowest clientId alphabetically).
+ *
+ * Returns { finalizedEpoch: -1, checkpoint: null } if no checkpoints exist.
+ */
+export declare function getFinalizedEpochAndCheckpoint(yCheckpoint: Y.Map<CheckpointRecord>): {
+    finalizedEpoch: number;
+    checkpoint: CheckpointRecord | null;
+};

package/dist/types/checkpoints.d.ts

@@ -0,0 +1,62 @@
+import { ClientId } from './ClientId';
+import { ClientState } from './clientState';
+import { JSONObject } from './json';
+import { TxRecord } from './TxRecord';
+import * as Y from "yjs";
+/**
+ * Watermarking for deduplication and pruning.
+ * - maxClock: All txs from this client with clock <= maxClock are FINALIZED.
+ * - maxWallClock: The last time we saw this client active (for pruning).
+ */
+type ClientWatermark = Readonly<{
+    maxClock: number;
+    maxWallClock: number;
+}>;
+/**
+ * Watermarks for all clients.
+ */
+export type ClientWatermarks = Record<ClientId, ClientWatermark>;
+/**
+ * A snapshot of the state at the end of a specific epoch.
+ */
+export type CheckpointRecord = {
+    state: JSONObject;
+    watermarks: ClientWatermarks;
+    txCount: number;
+    minWallClock: number;
+};
+/**
+ * Unique ID for a checkpoint.
+ * Format: `${epoch};${txCount};${clientId}`
+ */
+export type CheckpointKey = string;
+/**
+ * Data extracted from a checkpoint key.
+ */
+export type CheckpointKeyData = {
+    epoch: number;
+    txCount: number;
+    clientId: ClientId;
+};
+/**
+ * Helper to parse checkpoint keys.
+ * Checkpoint keys have format: `${epoch};${txCount};${clientId}`
+ * Throws if key is malformed.
+ */
+export declare function parseCheckpointKey(key: CheckpointKey): CheckpointKeyData;
+/**
+ * Called periodically (e.g. by a server or leader client) to finalize the epoch.
+ */
+export declare function createCheckpoint(yTx: Y.Map<TxRecord>, yCheckpoint: Y.Map<CheckpointRecord>, clientState: ClientState, activeEpoch: number, currentState: JSONObject, myClientId: string): void;
+/**
+ * Garbage collects old checkpoints.
+ * Should be called periodically to prevent unbounded growth of yCheckpoint.
+ *
+ * Keeps only the canonical checkpoint for the finalized epoch.
+ * Everything else is deleted (old epochs + non-canonical).
+ *
+ * Note: The active epoch never has checkpoints - creating a checkpoint
+ * for an epoch immediately makes it finalized.
+ */
+export declare function pruneCheckpoints(yCheckpoint: Y.Map<CheckpointRecord>, finalizedEpoch: number): void;
+export {};

package/dist/types/clientState.d.ts

@@ -0,0 +1,19 @@
+import { JSONObject } from './json';
+import { ValidateFn } from './operations';
+import { StateCalculator } from './StateCalculator';
+/**
+ * Client-side state including clocks and calculator for state management
+ */
+export interface ClientState {
+    localClock: number;
+    cachedFinalizedEpoch: number | null;
+    stateCalculator: StateCalculator;
+    /**
+     * Timestamp retention window in milliseconds.
+     */
+    retentionWindowMs: number;
+}
+/**
+ * Factory to create an initial ClientState
+ */
+export declare function createClientState(validateFn: ValidateFn<JSONObject> | undefined, retentionWindowMs: number): ClientState;

package/dist/types/createStateSyncLog.d.ts

@@ -0,0 +1,97 @@
+import { JSONObject } from './json';
+import { Op } from './operations';
+import { SortedTxEntry } from './SortedTxEntry';
+import * as Y from "yjs";
+export declare const getSortedTxsSymbol: unique symbol;
+export interface StateSyncLogOptions<State extends JSONObject> {
+    /**
+     * The Y.js Document to bind to.
+     */
+    yDoc: Y.Doc;
+    /**
+     * Name for the txs Y.Map.
+     * Default: "state-sync-log-tx"
+     */
+    yTxMapName?: string;
+    /**
+     * Name for the checkpoint Y.Map.
+     * Default: "state-sync-log-checkpoint"
+     */
+    yCheckpointMapName?: string;
+    /**
+     * Unique identifier for this client.
+     * If omitted, a random UUID (nanoid) will be generated.
+     * NOTE: If you need to resume a session (keep local clock/watermark), you MUST provide a stable ID.
+     * MUST NOT contain semicolons.
+     */
+    clientId?: string;
+    /**
+     * Origin tag for Y.js txs created by this library.
+     */
+    yjsOrigin?: unknown;
+    /**
+     * Optional validation function.
+     * Runs after each tx's ops are applied.
+     * If it returns false, the tx is rejected (state reverts).
+     * MUST be deterministic and consistent across all clients.
+     */
+    validate?: (state: State) => boolean;
+    /**
+     * Timestamp retention window in milliseconds.
+     * Txs older than this window are considered "Ancient" and pruned.
+     *
+     * Default: Infinity (No pruning).
+     * Recommended: 14 days (1209600000 ms).
+     */
+    retentionWindowMs: number | undefined;
+}
+export interface StateSyncLogController<State extends JSONObject> {
+    /**
+     * Returns the current state.
+     */
+    getState(): State;
+    /**
+     * Subscribes to state changes.
+     */
+    subscribe(callback: (newState: State, getAppliedOps: () => readonly Op[]) => void): () => void;
+    /**
+     * Emits a new tx (list of operations) to the log.
+     */
+    emit(ops: Op[]): void;
+    /**
+     * Reconciles the current state with the target state.
+     */
+    reconcileState(targetState: State): void;
+    /**
+     * Manually triggers epoch compaction (Checkpointing).
+     */
+    compact(): void;
+    /**
+     * Cleans up observers and releases memory.
+     */
+    dispose(): void;
+    /**
+     * Returns the current active epoch number.
+     */
+    getActiveEpoch(): number;
+    /**
+     * Returns the number of txs currently in the active epoch.
+     */
+    getActiveEpochTxCount(): number;
+    /**
+     * Returns the wallClock timestamp of the first tx in the active epoch.
+     */
+    getActiveEpochStartTime(): number | undefined;
+    /**
+     * Returns true if the log is completely empty.
+     */
+    isLogEmpty(): boolean;
+    /**
+     * Internal/Testing: Returns all txs currently in the log, sorted.
+     */
+    [getSortedTxsSymbol](): readonly SortedTxEntry[];
+}
+/**
+ * Creates a StateSyncLog controller.
+ */
+export declare function createStateSyncLog<State extends JSONObject>(options: StateSyncLogOptions<State>): StateSyncLogController<State>;

package/dist/types/draft.d.ts

@@ -0,0 +1,69 @@
+import { JSONObject, JSONValue, Path } from './json';
+import { Op, ValidateFn } from './operations';
+import { TxRecord } from './TxRecord';
+/**
+ * A draft context for copy-on-write immutable updates.
+ *
+ * This provides Immer/Mutative-like semantics without the proxy overhead:
+ * - The original base state is never mutated
+ * - Objects are cloned lazily on first mutation (copy-on-write)
+ * - Once an object is cloned ("owned"), it can be mutated directly
+ * - If no changes are made, the original reference is preserved (structural sharing)
+ */
+export interface DraftContext<T extends JSONObject> {
+    /** The current root (may be the original base or a cloned version) */
+    root: T;
+    /** The original base state (never mutated) */
+    base: T;
+    /** Set of objects that have been cloned and are safe to mutate */
+    ownedObjects: WeakSet<object>;
+    /** Optimization: fast check if root is already owned */
+    isRootOwned: boolean;
+}
+/**
+ * Creates a new draft context from a base state.
+ * The base state will never be mutated.
+ */
+export declare function createDraft<T extends JSONObject>(base: T): DraftContext<T>;
+/**
+ * Checks if the draft was modified (root !== base).
+ */
+export declare function isDraftModified<T extends JSONObject>(ctx: DraftContext<T>): boolean;
+/**
+ * Applies a single "set" operation to the draft with copy-on-write.
+ */
+export declare function draftSet<T extends JSONObject>(ctx: DraftContext<T>, path: Path, key: string, value: JSONValue): void;
+/**
+ * Applies a single "delete" operation to the draft with copy-on-write.
+ */
+export declare function draftDelete<T extends JSONObject>(ctx: DraftContext<T>, path: Path, key: string): void;
+/**
+ * Applies a single "splice" operation to the draft with copy-on-write.
+ */
+export declare function draftSplice<T extends JSONObject>(ctx: DraftContext<T>, path: Path, index: number, deleteCount: number, inserts: readonly JSONValue[]): void;
+/**
+ * Applies a single "addToSet" operation to the draft with copy-on-write.
+ */
+export declare function draftAddToSet<T extends JSONObject>(ctx: DraftContext<T>, path: Path, value: JSONValue): void;
+/**
+ * Applies a single "deleteFromSet" operation to the draft with copy-on-write.
+ */
+export declare function draftDeleteFromSet<T extends JSONObject>(ctx: DraftContext<T>, path: Path, value: JSONValue): void;
+/**
+ * Applies a single operation to the draft with copy-on-write.
+ */
+export declare function applyOpToDraft<T extends JSONObject>(ctx: DraftContext<T>, op: Op): void;
+/**
+ * Applies a single transaction to a base state immutably.
+ *
+ * Key benefits over Mutative/Immer:
+ * - No proxy overhead - direct object access and copy-on-write cloning
+ * - Structural sharing - unchanged subtrees keep their references
+ * - Zero-copy on failure - if validation fails, returns original base unchanged
+ *
+ * @param base - The base state (never mutated)
+ * @param tx - The transaction to apply
+ * @param validateFn - Optional validation function
+ * @returns The final state (if valid) or the original base (if invalid or empty)
+ */
+export declare function applyTxImmutable<T extends JSONObject>(base: T, tx: Pick<TxRecord, "ops">, validateFn?: ValidateFn<T>): T;

package/dist/types/error.d.ts

@@ -0,0 +1,4 @@
+export declare class StateSyncLogError extends Error {
+    constructor(msg: string);
+}
+export declare function failure(message: string): never;

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+export type { CheckpointKey, CheckpointRecord } from './checkpoints';
+export { createStateSyncLog, type StateSyncLogController, type StateSyncLogOptions, } from './createStateSyncLog';
+export type { JSONObject, JSONValue, Path } from './json';
+export { type ApplyOpsOptions, applyOps, type Op, type ValidateFn } from './operations';

package/dist/types/json.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A unique path to a value within the JSON document.
+ * Resolution fails if any segment is missing or type mismatch occurs.
+ */
+export type Path = readonly (string | number)[];
+/**
+ * A JSON primitive.
+ */
+export type JSONPrimitive = null | boolean | number | string;
+/**
+ * A JSON record.
+ */
+export type JSONRecord = {
+    [k: string]: JSONValue;
+};
+/**
+ * A JSON object.
+ */
+export type JSONObject = JSONRecord | JSONValue[];
+/**
+ * A JSON value.
+ */
+export type JSONValue = JSONPrimitive | JSONObject;

package/dist/types/operations.d.ts

@@ -0,0 +1,64 @@
+import { JSONObject, JSONValue, Path } from './json';
+/**
+ * Supported operations.
+ * Applied sequentially within a tx.
+ */
+export type Op = {
+    kind: "set";
+    path: Path;
+    key: string;
+    value: JSONValue;
+} | {
+    kind: "delete";
+    path: Path;
+    key: string;
+} | {
+    kind: "splice";
+    path: Path;
+    index: number;
+    deleteCount: number;
+    inserts: JSONValue[];
+} | {
+    kind: "addToSet";
+    path: Path;
+    value: JSONValue;
+} | {
+    kind: "deleteFromSet";
+    path: Path;
+    value: JSONValue;
+};
+/**
+ * Validation function type.
+ *
+ * Rules:
+ * - Validation MUST depend only on candidateState (and deterministic code).
+ * - Validation runs once per tx, after all ops apply.
+ * - If validation fails, the x is rejected (state reverts to previous).
+ * - If no validator is provided, validation defaults to true.
+ *
+ * IMPORTANT: Validation outcome is **derived local state** and MUST NOT be replicated.
+ * All clients MUST use the same validation logic to ensure consistency.
+ */
+export type ValidateFn<State extends JSONObject> = (candidateState: State) => boolean;
+/**
+ * Options for applyOps.
+ */
+export interface ApplyOpsOptions {
+    /**
+     * Whether to deep clone values before inserting them into the target.
+     * - `true` (default): Values are cloned to prevent aliasing between the ops and target.
+     * - `false`: Values are used directly for better performance. Only use this if you
+     *   guarantee the op values won't be mutated after application.
+     */
+    cloneValues?: boolean;
+}
+/**
+ * Applies a list of operations to a mutable target object.
+ * Use this to synchronize an external mutable state (e.g., MobX store)
+ * with the operations received via subscribe().
+ *
+ * @param ops - The list of operations to apply.
+ * @param target - The mutable object to modify.
+ * @param options - Optional settings for controlling cloning behavior.
+ */
+export declare function applyOps(ops: readonly Op[], target: JSONObject, options?: ApplyOpsOptions): void;

package/dist/types/reconcile.d.ts

@@ -0,0 +1,7 @@
+import { JSONValue } from './json';
+import { Op } from './operations';
+/**
+ * Reconciles the current state with the target state by computing and emitting
+ * the minimal set of operations needed to transform currentState into targetState.
+ */
+export declare function computeReconcileOps(currentState: JSONValue, targetState: JSONValue): Op[];

package/dist/types/txLog.d.ts

@@ -0,0 +1,32 @@
+import { CheckpointRecord } from './checkpoints';
+import { ClientState } from './clientState';
+import { JSONObject } from './json';
+import { Op } from './operations';
+import { TxRecord } from './TxRecord';
+import { TxTimestampKey } from './txTimestamp';
+import * as Y from "yjs";
+/**
+ * Changes to transaction keys from a Y.YMapEvent.
+ * - added: keys that were added
+ * - deleted: keys that were deleted
+ */
+export type TxKeyChanges = {
+    added: readonly TxTimestampKey[];
+    deleted: readonly TxTimestampKey[];
+};
+/**
+ * Appends a new transaction to the log.
+ *
+ * @param originalKey - Optional reference to the original transaction key for re-emits.
+ *                      Used by syncLog to preserve transactions missed by checkpoints.
+ */
+export declare function appendTx(ops: readonly Op[], yTx: Y.Map<TxRecord>, activeEpoch: number, myClientId: string, clientState: ClientState, originalKey?: TxTimestampKey): TxTimestampKey;
+/**
+ * The primary update function that maintains current state.
+ *
+ * @param txChanges - Changes from Y.YMapEvent. If undefined (first run), performs a full scan.
+ */
+export declare function updateState(doc: Y.Doc, yTx: Y.Map<TxRecord>, yCheckpoint: Y.Map<CheckpointRecord>, myClientId: string, clientState: ClientState, txChanges: TxKeyChanges | undefined): {
+    state: JSONObject;
+    getAppliedOps: () => readonly Op[];
+};

package/dist/types/txTimestamp.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Parsed tx timestamp components.
+ */
+export type TxTimestamp = {
+    epoch: number;
+    clock: number;
+    clientId: string;
+    wallClock: number;
+};
+/**
+ * Unique tx ID (Composite Key).
+ */
+export type TxTimestampKey = string;
+/**
+ * Converts a timestamp object to a TransactionTimestampKey string.
+ */
+export declare function txTimestampToKey(ts: TxTimestamp): TxTimestampKey;
+/**
+ * Helper to parse tx timestamp keys.
+ * Throws if key is malformed.
+ */
+export declare function parseTxTimestampKey(key: TxTimestampKey): TxTimestamp;
+/**
+ * Compares two tx timestamps for deterministic ordering.
+ * Sort order: epoch (asc) → clock (asc) → clientId (asc)
+ */
+export declare function compareTxTimestamps(a: TxTimestamp, b: TxTimestamp): number;

package/dist/types/utils.d.ts

@@ -0,0 +1,23 @@
+import { JSONValue } from './json';
+/**
+ * Deep equality check for JSONValues.
+ * Used for addToSet / deleteFromSet operations.
+ */
+export declare function deepEqual(a: JSONValue, b: JSONValue): boolean;
+/**
+ * Generates a unique ID using nanoid.
+ */
+export declare function generateID(): string;
+/**
+ * Checks if a value is an object (typeof === "object" && !== null).
+ */
+export declare function isObject(value: unknown): value is object;
+/**
+ * Deep clones a JSON-serializable value.
+ * Optimized: primitives are returned as-is.
+ */
+export declare function deepClone<T>(value: T): T;
+/**
+ * Creates a lazy memoized getter.
+ */
+export declare function lazy<T>(fn: () => T): () => T;