@enbox/api 0.2.3 → 0.3.0

package/dist/esm/repository.js

@@ -0,0 +1,347 @@
+/**
+ * Protocol-aware repository factory.
+ *
+ * `repository()` takes a `TypedWeb5` instance and returns a Proxy-backed
+ * object whose shape mirrors the protocol's `structure` tree with
+ * ergonomic CRUD methods on each node.
+ *
+ * - **Collections** (default): `create`, `query`, `get`, `delete`, `subscribe`
+ * - **Singletons** (`$recordLimit: { max: 1 }`): `set`, `get`, `delete`
+ * - **Nested types**: first argument is `parentContextId`
+ * - **`configure()`**: idempotent protocol installation
+ *
+ * @example
+ * ```ts
+ * const social = repository(web5.using(SocialGraphProtocol));
+ * await social.configure();
+ *
+ * // Root collection
+ * const { record } = await social.friend.create({
+ *   data: { did: 'did:example:alice' },
+ * });
+ *
+ * // Nested under group
+ * const members = await social.group.member.query(groupContextId);
+ * ```
+ *
+ * @module
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+// ---------------------------------------------------------------------------
+// Runtime helpers
+// ---------------------------------------------------------------------------
+/**
+ * Checks whether a DWN response status indicates that the record limit
+ * has been exceeded. The DWN engine returns a 400 status with a detail
+ * message containing "record limit" when `$recordLimit` rejects a write.
+ */
+function isRecordLimitExceeded(status) {
+    return status.code === 400 && status.detail.includes('record limit');
+}
+/**
+ * Checks whether a protocol rule set at a given path is a singleton
+ * (has `$recordLimit: { max: 1 }`).
+ */
+function isSingletonPath(definition, path) {
+    const segments = path.split('/');
+    let node = definition.structure;
+    for (const seg of segments) {
+        if (!node || typeof node !== 'object') {
+            return false;
+        }
+        node = node[seg];
+    }
+    if (!node || typeof node !== 'object') {
+        return false;
+    }
+    const limit = node['$recordLimit'];
+    return limit !== undefined
+        && typeof limit === 'object'
+        && limit !== null
+        && limit['max'] === 1;
+}
+/**
+ * Returns the child type keys (non-`$`-prefixed) of a rule set node
+ * reached by the given path.
+ */
+function getChildKeys(definition, path) {
+    const segments = path.split('/');
+    let node = definition.structure;
+    for (const seg of segments) {
+        if (!node || typeof node !== 'object') {
+            return [];
+        }
+        node = node[seg];
+    }
+    if (!node || typeof node !== 'object') {
+        return [];
+    }
+    return Object.keys(node).filter((k) => !k.startsWith('$'));
+}
+// ---------------------------------------------------------------------------
+// CRUD method builders
+// ---------------------------------------------------------------------------
+/**
+ * Build collection CRUD methods for a root-level path.
+ */
+function buildRootCollectionMethods(typed, path) {
+    return {
+        create(options) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const { status, record } = yield typed.records.create(path, options);
+                return { status, record };
+            });
+        },
+        query(options) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const { status, records, cursor } = yield typed.records.query(path, options);
+                return { status, records, cursor };
+            });
+        },
+        get(recordId) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const { record } = yield typed.records.read(path, {
+                    filter: { recordId },
+                });
+                return record;
+            });
+        },
+        delete(recordId) {
+            return __awaiter(this, void 0, void 0, function* () {
+                return typed.records.delete(path, { recordId });
+            });
+        },
+        subscribe(options) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const { liveQuery } = yield typed.records.subscribe(path, options);
+                return liveQuery;
+            });
+        },
+    };
+}
+/**
+ * Build singleton CRUD methods for a root-level path.
+ *
+ * Uses a create-first strategy: attempts to create a new record, and if the
+ * DWN rejects it because the record limit is reached, falls back to querying
+ * the existing record and updating it. This avoids the race condition inherent
+ * in query-then-create/update.
+ */
+function buildRootSingletonMethods(typed, path) {
+    return {
+        set(options) {
+            return __awaiter(this, void 0, void 0, function* () {
+                // Attempt to create — if limit not yet reached, this succeeds.
+                const createResult = yield typed.records.create(path, options);
+                if (isRecordLimitExceeded(createResult.status)) {
+                    // Record limit hit — query existing and update.
+                    const { records } = yield typed.records.query(path);
+                    if (records.length > 0) {
+                        const { status, record } = yield records[0].update(Object.assign({ data: options.data }, (options.tags !== undefined ? { tags: options.tags } : {})));
+                        return { status, record };
+                    }
+                }
+                return { status: createResult.status, record: createResult.record };
+            });
+        },
+        get() {
+            return __awaiter(this, void 0, void 0, function* () {
+                const { records } = yield typed.records.query(path);
+                return records.length > 0 ? records[0] : undefined;
+            });
+        },
+        delete(recordId) {
+            return __awaiter(this, void 0, void 0, function* () {
+                return typed.records.delete(path, { recordId });
+            });
+        },
+    };
+}
+/**
+ * Build collection CRUD methods for a nested path.
+ */
+function buildNestedCollectionMethods(typed, path) {
+    return {
+        create(parentContextId, options) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const { status, record } = yield typed.records.create(path, Object.assign(Object.assign({}, options), { parentContextId }));
+                return { status, record };
+            });
+        },
+        query(parentContextId, options) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const { status, records, cursor } = yield typed.records.query(path, Object.assign(Object.assign({}, options), { filter: Object.assign(Object.assign({}, options === null || options === void 0 ? void 0 : options.filter), { contextId: parentContextId }) }));
+                return { status, records, cursor };
+            });
+        },
+        get(recordId) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const { record } = yield typed.records.read(path, {
+                    filter: { recordId },
+                });
+                return record;
+            });
+        },
+        delete(recordId) {
+            return __awaiter(this, void 0, void 0, function* () {
+                return typed.records.delete(path, { recordId });
+            });
+        },
+        subscribe(parentContextId, options) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const { liveQuery } = yield typed.records.subscribe(path, Object.assign(Object.assign({}, options), { filter: Object.assign(Object.assign({}, options === null || options === void 0 ? void 0 : options.filter), { contextId: parentContextId }) }));
+                return liveQuery;
+            });
+        },
+    };
+}
+/**
+ * Build singleton CRUD methods for a nested path.
+ *
+ * Uses the same create-first strategy as root singletons to avoid race
+ * conditions between concurrent set() calls.
+ */
+function buildNestedSingletonMethods(typed, path) {
+    return {
+        set(parentContextId, options) {
+            return __awaiter(this, void 0, void 0, function* () {
+                // Attempt to create under this parent — succeeds if no record exists yet.
+                const createResult = yield typed.records.create(path, Object.assign(Object.assign({}, options), { parentContextId }));
+                if (isRecordLimitExceeded(createResult.status)) {
+                    // Record limit hit — query existing under this parent and update.
+                    const { records } = yield typed.records.query(path, {
+                        filter: { contextId: parentContextId },
+                    });
+                    if (records.length > 0) {
+                        const { status, record } = yield records[0].update(Object.assign({ data: options.data }, (options.tags !== undefined ? { tags: options.tags } : {})));
+                        return { status, record };
+                    }
+                }
+                return { status: createResult.status, record: createResult.record };
+            });
+        },
+        get(parentContextId) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const { records } = yield typed.records.query(path, {
+                    filter: { contextId: parentContextId },
+                });
+                return records.length > 0 ? records[0] : undefined;
+            });
+        },
+        delete(recordId) {
+            return __awaiter(this, void 0, void 0, function* () {
+                return typed.records.delete(path, { recordId });
+            });
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Node builder
+// ---------------------------------------------------------------------------
+/**
+ * Build a repository node for a given path, including CRUD methods
+ * and Proxy-based child nodes.
+ */
+function buildNode(typed, definition, path, isNested) {
+    const singleton = isSingletonPath(definition, path);
+    // Build CRUD methods based on root/nested and singleton/collection
+    let methods;
+    if (isNested) {
+        methods = singleton
+            ? buildNestedSingletonMethods(typed, path)
+            : buildNestedCollectionMethods(typed, path);
+    }
+    else {
+        methods = singleton
+            ? buildRootSingletonMethods(typed, path)
+            : buildRootCollectionMethods(typed, path);
+    }
+    // Use a Proxy to lazily build child nodes
+    const childKeys = getChildKeys(definition, path);
+    const childCache = {};
+    return new Proxy(methods, {
+        get(target, prop) {
+            if (typeof prop !== 'string') {
+                return undefined;
+            }
+            // CRUD methods take priority
+            if (prop in target) {
+                return target[prop];
+            }
+            // Lazily build child nodes
+            if (childKeys.includes(prop)) {
+                if (!(prop in childCache)) {
+                    childCache[prop] = buildNode(typed, definition, `${path}/${prop}`, true);
+                }
+                return childCache[prop];
+            }
+            return undefined;
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Creates a protocol-aware repository from a `TypedWeb5` instance.
+ *
+ * The returned object provides domain-specific CRUD methods that mirror
+ * the protocol's structure tree:
+ *
+ * - Root types: `repo.friend.create()`, `repo.friend.query()`
+ * - Nested types: `repo.group.member.create(groupCtxId, { data })`
+ * - Singletons: `repo.profile.set()`, `repo.profile.get()`
+ * - Protocol install: `repo.configure()`
+ *
+ * @param typed - A `TypedWeb5` instance from `web5.using(protocol)`.
+ * @returns A typed repository object.
+ *
+ * @example
+ * ```ts
+ * const social = repository(web5.using(SocialGraphProtocol));
+ * await social.configure();
+ *
+ * const rec = await social.friend.create({
+ *   data: { did: 'did:example:alice' },
+ * });
+ * const friends = await social.friend.query();
+ * ```
+ */
+export function repository(typed) {
+    const definition = typed.definition;
+    // Get root-level type keys from the structure
+    const rootKeys = Object.keys(definition.structure).filter((k) => !k.startsWith('$'));
+    const nodeCache = {};
+    const proxy = new Proxy({}, {
+        get(_target, prop) {
+            if (typeof prop !== 'string') {
+                return undefined;
+            }
+            // configure() method
+            if (prop === 'configure') {
+                return (options) => __awaiter(this, void 0, void 0, function* () {
+                    const result = yield typed.configure(options);
+                    return result;
+                });
+            }
+            // Root-level type nodes
+            if (rootKeys.includes(prop)) {
+                if (!(prop in nodeCache)) {
+                    nodeCache[prop] = buildNode(typed, definition, prop, false);
+                }
+                return nodeCache[prop];
+            }
+            return undefined;
+        },
+    });
+    return proxy;
+}
+//# sourceMappingURL=repository.js.map

package/dist/esm/repository.js.map

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

package/dist/esm/typed-live-query.js

@@ -0,0 +1,129 @@
+/**
+ * A type-safe wrapper around {@link LiveQuery} that carries the data type `T`
+ * through initial snapshot records and real-time change events.
+ *
+ * `TypedLiveQuery<T>` wraps a `LiveQuery` so that:
+ * - `.records` returns `TypedRecord<T>[]` instead of `Record[]`.
+ * - `.on('create', handler)` provides `TypedRecord<T>` in the callback.
+ * - `.on('change', handler)` provides `TypedRecordChange<T>` in the callback.
+ * - `.on('disconnected' | 'reconnecting' | 'reconnected' | 'eose', handler)`
+ *   forwards transport lifecycle events from the underlying `LiveQuery`.
+ *
+ * @example
+ * ```ts
+ * const { liveQuery } = await typed.records.subscribe('friend');
+ * // liveQuery is TypedLiveQuery<FriendData>
+ *
+ * for (const record of liveQuery.records) {
+ *   const data = await record.data.json(); // FriendData
+ * }
+ *
+ * liveQuery.on('create', async (record) => {
+ *   const data = await record.data.json(); // FriendData
+ * });
+ *
+ * // Connection lifecycle events
+ * liveQuery.on('disconnected', () => showOfflineIndicator());
+ * liveQuery.on('reconnected', () => hideOfflineIndicator());
+ * liveQuery.on('eose', () => console.log('catch-up complete'));
+ * ```
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { TypedRecord } from './typed-record.js';
+// ---------------------------------------------------------------------------
+// TypedLiveQuery class
+// ---------------------------------------------------------------------------
+/**
+ * A type-safe wrapper around {@link LiveQuery} that preserves the data type `T`
+ * through the initial snapshot and all subsequent change events.
+ *
+ * Obtain instances through `TypedWeb5.records.subscribe()` — never construct
+ * directly.
+ */
+export class TypedLiveQuery {
+    constructor(liveQuery) {
+        this._liveQuery = liveQuery;
+    }
+    // -------------------------------------------------------------------------
+    // Escape hatch
+    // -------------------------------------------------------------------------
+    /** Access the underlying untyped {@link LiveQuery} for advanced use cases. */
+    get rawLiveQuery() {
+        return this._liveQuery;
+    }
+    // -------------------------------------------------------------------------
+    // Typed initial snapshot
+    // -------------------------------------------------------------------------
+    /** The initial snapshot of matching records, typed as `TypedRecord<T>[]`. */
+    get records() {
+        if (!this._typedRecords) {
+            this._typedRecords = this._liveQuery.records.map((record) => new TypedRecord(record));
+        }
+        return this._typedRecords;
+    }
+    /**
+     * Pagination cursor for fetching the next page of initial results.
+     *
+     * `undefined` when there are no more results.
+     */
+    get cursor() {
+        return this._liveQuery.cursor;
+    }
+    /**
+     * Whether the transport connection is currently active.
+     * Delegates to the underlying `LiveQuery.isConnected`.
+     */
+    get isConnected() {
+        return this._liveQuery.isConnected;
+    }
+    on(event, handler) {
+        // Lifecycle events: delegate directly to the underlying LiveQuery.
+        if (event === 'disconnected') {
+            return this._liveQuery.on('disconnected', handler);
+        }
+        if (event === 'reconnected') {
+            return this._liveQuery.on('reconnected', handler);
+        }
+        if (event === 'eose') {
+            return this._liveQuery.on('eose', handler);
+        }
+        if (event === 'reconnecting') {
+            return this._liveQuery.on('reconnecting', handler);
+        }
+        // Record change events: wrap records in TypedRecord.
+        if (event === 'change') {
+            return this._liveQuery.on('change', (change) => {
+                handler({
+                    type: change.type,
+                    record: new TypedRecord(change.record),
+                });
+            });
+        }
+        // For create/update/delete, the underlying LiveQuery handler receives a Record.
+        // Cast event to 'create' to satisfy the overload resolver — the actual value
+        // is always one of 'create' | 'update' | 'delete' at this point.
+        return this._liveQuery.on(event, (record) => {
+            handler(new TypedRecord(record));
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Lifecycle
+    // -------------------------------------------------------------------------
+    /**
+     * Close the underlying subscription and stop dispatching events.
+     */
+    close() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this._liveQuery.close();
+        });
+    }
+}
+//# sourceMappingURL=typed-live-query.js.map

package/dist/esm/typed-live-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typed-live-query.js","sourceRoot":"","sources":["../../src/typed-live-query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;;;;;;;;;;AAKH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAoBhD,8EAA8E;AAC9E,uBAAuB;AACvB,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,OAAO,cAAc;IAOzB,YAAY,SAAoB;QAC9B,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;IAC9B,CAAC;IAED,4EAA4E;IAC5E,eAAe;IACf,4EAA4E;IAE5E,8EAA8E;IAC9E,IAAW,YAAY;QACrB,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED,4EAA4E;IAC5E,yBAAyB;IACzB,4EAA4E;IAE5E,6EAA6E;IAC7E,IAAW,OAAO;QAChB,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;YACxB,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,CAC9C,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,WAAW,CAAI,MAAM,CAAC,CACvC,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC,aAAa,CAAC;IAC5B,CAAC;IAED;;;;OAIG;IACH,IAAW,MAAM;QACf,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;IAChC,CAAC;IAED;;;OAGG;IACH,IAAW,WAAW;QACpB,OAAO,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC;IACrC,CAAC;IAoCM,EAAE,CACP,KAA2G,EAC3G,OAGgB;QAEhB,mEAAmE;QACnE,IAAI,KAAK,KAAK,cAAc,EAAE,CAAC;YAC7B,OAAO,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,cAAc,EAAE,OAAqB,CAAC,CAAC;QACnE,CAAC;QACD,IAAI,KAAK,KAAK,aAAa,EAAE,CAAC;YAC5B,OAAO,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,aAAa,EAAE,OAAqB,CAAC,CAAC;QAClE,CAAC;QACD,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;YACrB,OAAO,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,OAAqB,CAAC,CAAC;QAC3D,CAAC;QACD,IAAI,KAAK,KAAK,cAAc,EAAE,CAAC;YAC7B,OAAO,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,cAAc,EAAE,OAAgD,CAAC,CAAC;QAC9F,CAAC;QAED,qDAAqD;QACrD,IAAI,KAAK,KAAK,QAAQ,EAAE,CAAC;YACvB,OAAO,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,MAAoB,EAAQ,EAAE;gBAChE,OAAkD,CAAC;oBAClD,IAAI,EAAK,MAAM,CAAC,IAAI;oBACpB,MAAM,EAAG,IAAI,WAAW,CAAI,MAAM,CAAC,MAAM,CAAC;iBAC3C,CAAC,CAAC;YACL,CAAC,CAAC,CAAC;QACL,CAAC;QAED,gFAAgF;QAChF,6EAA6E;QAC7E,iEAAiE;QACjE,OAAO,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,KAAiB,EAAE,CAAC,MAAM,EAAQ,EAAE;YAC3D,OAA4C,CAAC,IAAI,WAAW,CAAI,MAAM,CAAC,CAAC,CAAC;QAC5E,CAAC,CAAC,CAAC;IACL,CAAC;IAED,4EAA4E;IAC5E,YAAY;IACZ,4EAA4E;IAE5E;;OAEG;IACU,KAAK;;YAChB,OAAO,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QACjC,CAAC;KAAA;CACF"}