@tangleai/context 0.21.1 → 0.24.1

package/src/storage/slot.js

@@ -1,107 +1,115 @@
-//@ts-check
 /** A whole-slot ledger adapter. Reload under the shared Web Lock before writes. */
 const copy = (value) => value === undefined ? undefined : JSON.parse(JSON.stringify(value));
-
 /**
  * JSON slots must report failed writes by throwing or returning false. A legacy
  * slot that swallows errors cannot promise durability; status says unverified.
  * Web Locks serialize tabs using the same slot name. Without them the adapter
  * explicitly exposes only the four-method, single-writer contract.
- * @param {{ read: () => any, write: (data: any) => any, key?: string, reliable?: boolean }} slot
- * @param {{ locks?: any, name?: string, singleWriter?: boolean }} [options]
+ * @param [options]
  */
 export function createSlotLedgerStorage(slot, options = {}) {
-  const locks = options.locks;
-  const name = options.name ?? slot.key ?? 'jaren-ai-ledger';
-  let closed = false;
-  const active = () => { if (closed) throw new Error('The ledger storage adapter is closed.'); };
-  let cache = {};
-  let error = null;
-  let durable = slot.reliable === true ? 'durable' : 'unverified';
-  const load = () => {
-    active();
-    const raw = slot.read();
-    if (raw !== null && raw !== undefined && (typeof raw !== 'object' || Array.isArray(raw)))
-      throw new TypeError('invalid ledger slot: expected a record map');
-    cache = copy(raw ?? {});
-    return cache;
-  };
-  const publish = (next) => {
-    active();
-    try {
-      if (slot.write(next) === false) throw new Error('ledger storage write failed');
-      cache = copy(next);
-      error = null;
-      durable = slot.reliable === true ? 'durable' : 'unverified';
-    }
-    catch (cause) {
-      error = cause instanceof Error ? cause.message : String(cause);
-      durable = 'failed';
-      throw cause;
-    }
-  };
-  const atomic = typeof locks?.request === 'function';
-  // WebKit's process-local storage snapshots can remain stale even across a
-  // locked task boundary. Elect one owner there instead of claiming coherence.
-  const singleWriter = options.singleWriter ?? false;
-  let ownership;
-  let releaseOwner;
-  let ownerRequest;
-  const own = () => {
-    active();
-    if (!atomic || !singleWriter) return Promise.resolve();
-    ownership ??= new Promise((resolve, reject) => {
-      const held = new Promise((release) => { releaseOwner = release; });
-      ownerRequest = locks.request(`ledger-owner:${name}`, { ifAvailable: true }, (lock) => {
-        if (!lock) {
-          reject(new Error('single-writer ledger: another tab owns this storage; close that tab before writing here'));
-          return;
+    const locks = options.locks;
+    const name = options.name ?? slot.key ?? 'jaren-ai-ledger';
+    let closed = false;
+    const active = () => { if (closed)
+        throw new Error('The ledger storage adapter is closed.'); };
+    let cache = {};
+    let error = null;
+    let durable = slot.reliable === true ? 'durable' : 'unverified';
+    const load = () => {
+        active();
+        const raw = slot.read();
+        if (raw !== null && raw !== undefined && (typeof raw !== 'object' || Array.isArray(raw)))
+            throw new TypeError('invalid ledger slot: expected a record map');
+        cache = copy(raw ?? {});
+        return cache;
+    };
+    const publish = (next) => {
+        active();
+        try {
+            if (slot.write(next) === false)
+                throw new Error('ledger storage write failed');
+            cache = copy(next);
+            error = null;
+            durable = slot.reliable === true ? 'durable' : 'unverified';
         }
-        resolve();
-        return held;
-      });
-      ownerRequest.catch(reject);
-    });
-    ownership.catch(() => { ownership = undefined; });
-    return ownership;
-  };
-  // Firefox publishes localStorage snapshots at task boundaries. Keep the
-  // lock until that publication completes, and enter a fresh task before read.
-  const taskBoundary = () => new Promise((resolve) => setTimeout(resolve, 0));
-  const locked = (fn) => atomic ? locks.request(`ledger:${name}`, async () => {
-    await taskBoundary();
-    try { return fn(); }
-    finally { await taskBoundary(); }
-  }) : Promise.resolve().then(fn);
-  const mutate = async (prefix, transform) => {
-    await own();
-    return locked(() => {
-    const matches = (key) => typeof prefix === 'string' ? key.startsWith(prefix)
-      : (prefix.keys ?? []).includes(key) || (prefix.prefixes ?? []).some((part) => key.startsWith(part));
-    const current = load();
-    const scoped = Object.fromEntries(Object.keys(current).sort()
-      .filter((key) => matches(key)).map((key) => [key, copy(current[key])]));
-    const outcome = transform(scoped);
-    if (!outcome || typeof outcome.then === 'function') throw new TypeError('mutate callback must be synchronous');
-    if (outcome.next !== undefined) {
-      const next = copy(outcome.next);
-      if (Object.keys(next).some((key) => !matches(key))) throw new TypeError('mutation escaped its namespace');
-      for (const key of Object.keys(current)) if (matches(key)) delete current[key];
-      publish({ ...current, ...next });
-    }
-    return outcome.result;
-    });
-  };
-  return {
-    ...(atomic ? { mutate } : {}),
-    status: () => ({ concurrency: atomic && !singleWriter ? 'atomic' : 'single-writer', durability: durable, error }),
-    close: async () => { closed = true; releaseOwner?.(); await ownerRequest; ownership = undefined; },
-    get: async (key) => { await own(); return copy(load()[key]); },
-    set: (key, value) => mutate('', (current) => ({ next: { ...current, [key]: copy(value) } })),
-    delete: (key) => mutate('', (current) => {
-      delete current[key];
-      return { next: current };
-    }),
-    keys: async (prefix = '') => { await own(); return Object.keys(load()).filter((key) => key.startsWith(prefix)).sort(); },
-  };
+        catch (cause) {
+            error = cause instanceof Error ? cause.message : String(cause);
+            durable = 'failed';
+            throw cause;
+        }
+    };
+    const atomic = typeof locks?.request === 'function';
+    // WebKit's process-local storage snapshots can remain stale even across a
+    // locked task boundary. Elect one owner there instead of claiming coherence.
+    const singleWriter = options.singleWriter ?? false;
+    let ownership;
+    let releaseOwner;
+    let ownerRequest;
+    const own = () => {
+        active();
+        if (!atomic || !singleWriter)
+            return Promise.resolve();
+        ownership ??= new Promise((resolve, reject) => {
+            const held = new Promise((release) => { releaseOwner = release; });
+            ownerRequest = locks.request(`ledger-owner:${name}`, { ifAvailable: true }, (lock) => {
+                if (!lock) {
+                    reject(new Error('single-writer ledger: another tab owns this storage; close that tab before writing here'));
+                    return;
+                }
+                resolve();
+                return held;
+            });
+            ownerRequest.catch(reject);
+        });
+        ownership.catch(() => { ownership = undefined; });
+        return ownership;
+    };
+    // Firefox publishes localStorage snapshots at task boundaries. Keep the
+    // lock until that publication completes, and enter a fresh task before read.
+    const taskBoundary = () => new Promise((resolve) => setTimeout(resolve, 0));
+    const locked = (fn) => atomic ? locks.request(`ledger:${name}`, async () => {
+        await taskBoundary();
+        try {
+            return fn();
+        }
+        finally {
+            await taskBoundary();
+        }
+    }) : Promise.resolve().then(fn);
+    const mutate = async (prefix, transform) => {
+        await own();
+        return locked(() => {
+            const matches = (key) => typeof prefix === 'string' ? key.startsWith(prefix)
+                : (prefix.keys ?? []).includes(key) || (prefix.prefixes ?? []).some((part) => key.startsWith(part));
+            const current = load();
+            const scoped = Object.fromEntries(Object.keys(current).sort()
+                .filter((key) => matches(key)).map((key) => [key, copy(current[key])]));
+            const outcome = transform(scoped);
+            if (!outcome || typeof outcome.then === 'function')
+                throw new TypeError('mutate callback must be synchronous');
+            if (outcome.next !== undefined) {
+                const next = copy(outcome.next);
+                if (Object.keys(next).some((key) => !matches(key)))
+                    throw new TypeError('mutation escaped its namespace');
+                for (const key of Object.keys(current))
+                    if (matches(key))
+                        delete current[key];
+                publish({ ...current, ...next });
+            }
+            return outcome.result;
+        });
+    };
+    return {
+        ...(atomic ? { mutate } : {}),
+        status: () => ({ concurrency: atomic && !singleWriter ? 'atomic' : 'single-writer', durability: durable, error }),
+        close: async () => { closed = true; releaseOwner?.(); await ownerRequest; ownership = undefined; },
+        get: async (key) => { await own(); return copy(load()[key]); },
+        set: (key, value) => mutate('', (current) => ({ next: { ...current, [key]: copy(value) } })),
+        delete: (key) => mutate('', (current) => {
+            delete current[key];
+            return { next: current };
+        }),
+        keys: async (prefix = '') => { await own(); return Object.keys(load()).filter((key) => key.startsWith(prefix)).sort(); },
+    };
 }

package/src/storage/transaction.d.ts

@@ -1,32 +1,17 @@
+/** Whether a private view is already enclosed by an atomic publication. */
+export declare const isAtomicView: (view: any) => boolean;
 /**
  * Stage async ledger work off-store, then publish through one synchronous CAS.
  * Readers never observe the staged adapter. Competing commits retry against a
  * fresh record map; external I/O belongs outside the transform callback.
  * Four-method adapters retain their explicit single-writer behavior.
  * @template T
- * @param {any} storage
- * @param {StorageScope} prefix
- * @param {(view: any) => Promise<T>} task
- * @returns {Promise<T>}
- */
-export function atomicTask<T>(storage: any, prefix: StorageScope, task: (view: any) => Promise<T>): Promise<T>;
-export function isAtomicView(view: any): boolean;
-/**
- * Atomically transform the JSON record map under a namespace. The synchronous
- * callback receives a detached current map and returns {next, result}; omitting
- * next is a read-only decision. Failure publishes nothing. Keys cannot escape
- * the namespace. Adapters serialize the callback with every other write.
  */
+export declare function atomicTask<T>(storage: any, prefix: StorageScope, task: (view: any) => Promise<T>): Promise<T>;
 export type StorageScope = string | {
     prefixes?: string[];
     keys?: string[];
 };
-/**
- * Atomically transform the JSON record map under a namespace. The synchronous
- * callback receives a detached current map and returns {next, result}; omitting
- * next is a read-only decision. Failure publishes nothing. Keys cannot escape
- * the namespace. Adapters serialize the callback with every other write.
- */
 export type StorageMutation = (prefix: StorageScope, transform: (current: Record<string, any>) => {
     next?: Record<string, any>;
     result?: any;

package/src/storage/transaction.js

@@ -1,49 +1,37 @@
-//@ts-check
-import { createMemoryStorage } from './memory.js';
-
-/**
- * Atomically transform the JSON record map under a namespace. The synchronous
+import { createMemoryStorage } from "./memory.js";
+/** Atomically transform the JSON record map under a namespace. The synchronous
  * callback receives a detached current map and returns {next, result}; omitting
  * next is a read-only decision. Failure publishes nothing. Keys cannot escape
- * the namespace. Adapters serialize the callback with every other write.
- * @typedef {string | { prefixes?: string[], keys?: string[] }} StorageScope
- * @typedef {(prefix: StorageScope, transform: (current: Record<string, any>) =>
- *   { next?: Record<string, any>, result?: any }) => Promise<any>} StorageMutation
- */
-
+ * the namespace. Adapters serialize the callback with every other write. */
 const staged = new WeakSet();
 /** Whether a private view is already enclosed by an atomic publication. */
 export const isAtomicView = (view) => staged.has(view);
-
 const signature = (map) => JSON.stringify(Object.keys(map).sort().map((key) => [key, map[key]]));
-
 /**
  * Stage async ledger work off-store, then publish through one synchronous CAS.
  * Readers never observe the staged adapter. Competing commits retry against a
  * fresh record map; external I/O belongs outside the transform callback.
  * Four-method adapters retain their explicit single-writer behavior.
  * @template T
- * @param {any} storage
- * @param {StorageScope} prefix
- * @param {(view: any) => Promise<T>} task
- * @returns {Promise<T>}
  */
 export async function atomicTask(storage, prefix, task) {
-  if (typeof storage.mutate !== 'function') return task(storage);
-  for (let attempt = 0; attempt < 128; attempt++) {
-    const before = await storage.mutate(prefix, (current) => ({ result: current }));
-    const expected = signature(before);
-    const backing = new Map(Object.entries(before).map(([key, value]) => [key, JSON.stringify(value)]));
-    const view = createMemoryStorage(backing);
-    // Staging already owns its isolated map; nested transactions need no CAS.
-    const { mutate: _mutate, ...plain } = view;
-    staged.add(plain);
-    const result = await task(plain);
-    const next = Object.fromEntries([...backing].map(([key, raw]) => [key, JSON.parse(raw)]));
-    const changed = signature(next) !== expected;
-    const committed = await storage.mutate(prefix, (current) => signature(current) !== expected
-      ? { result: false } : { ...(changed ? { next } : {}), result: true });
-    if (committed) return result;
-  }
-  throw Object.assign(new Error('ledger transaction conflict; retry the operation'), { code: 'LEDGER_CONFLICT' });
+    if (typeof storage.mutate !== 'function')
+        return task(storage);
+    for (let attempt = 0; attempt < 128; attempt++) {
+        const before = await storage.mutate(prefix, (current) => ({ result: current }));
+        const expected = signature(before);
+        const backing = new Map(Object.entries(before).map(([key, value]) => [key, JSON.stringify(value)]));
+        const view = createMemoryStorage(backing);
+        // Staging already owns its isolated map; nested transactions need no CAS.
+        const { mutate: _mutate, ...plain } = view;
+        staged.add(plain);
+        const result = await task(plain);
+        const next = Object.fromEntries([...backing].map(([key, raw]) => [key, JSON.parse(raw)]));
+        const changed = signature(next) !== expected;
+        const committed = await storage.mutate(prefix, (current) => signature(current) !== expected
+            ? { result: false } : { ...(changed ? { next } : {}), result: true });
+        if (committed)
+            return result;
+    }
+    throw Object.assign(new Error('ledger transaction conflict; retry the operation'), { code: 'LEDGER_CONFLICT' });
 }