@private.me/xbind 3.0.1 → 3.0.2

package/dist-standalone/cjs/batch-operations.js

@@ -1 +1,397 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.BatchOperationError=void 0,exports.batchSend=batchSend,exports.batchReceive=batchReceive,exports.batchRegistryOps=batchRegistryOps,exports.batchResolve=batchResolve,exports.batchGetEntries=batchGetEntries;const shared_1=require("../_deps/shared/index.js"),ux_helpers_1=require("../_deps/ux-helpers/index.js");class BatchOperationError extends Error{summary;constructor(e,t){super(e),this.summary=t,this.name="BatchOperationError"}}async function batchSend(e,t){const r=new ux_helpers_1.ProgressReporter(t.onProgress),n=Date.now(),{messages:s,strategy:o="parallel",concurrency:a=10,continueOnError:c=!0}=t;r.start(`Sending ${s.length} messages (${o} mode)...`);const i=[];if("sequential"===o)for(let t=0;t<s.length;t++){const n=s[t],o=Date.now();r.update(`Sending message ${t+1}/${s.length}...`,t/s.length*100);const a=await e.send(n),u=Date.now()-o;if(i.push({index:t,result:a,durationMs:u}),!c&&!a.ok)break}else if("failfast"===o){const t=s.map((t,r)=>{const s=Date.now();return e.send(t).then(e=>{const t=Date.now()-s;if(!e.ok)throw new BatchOperationError(`Batch send failed at index ${r}: ${e.error}`,createSummary(i,Date.now()-n));return{index:r,result:e,durationMs:t}})});try{const e=await Promise.all(t);i.push(...e)}catch(e){if(e instanceof BatchOperationError)throw e;throw new BatchOperationError("Batch send failed",createSummary(i,Date.now()-n))}}else{const t=chunkArray(s,a);for(let n=0;n<t.length;n++){const s=t[n],o=n*a;r.update(`Processing chunk ${n+1}/${t.length}...`,n/t.length*100);const c=await Promise.all(s.map(async(t,r)=>{const n=o+r,s=Date.now();return{index:n,result:await e.send(t),durationMs:Date.now()-s}}));i.push(...c)}}return r.complete(),createSummary(i,Date.now()-n)}async function batchReceive(e,t){const r=new ux_helpers_1.ProgressReporter(t.onProgress),n=Date.now(),{envelopes:s,receiveOptions:o,strategy:a="parallel",concurrency:c=10,continueOnError:i=!0}=t;r.start(`Receiving ${s.length} envelopes (${a} mode)...`);const u=[];if("sequential"===a)for(let t=0;t<s.length;t++){const n=s[t],a=Date.now();r.update(`Receiving envelope ${t+1}/${s.length}...`,t/s.length*100);const c=await e.receive(n,o),l=Date.now()-a;if(u.push({index:t,result:c,durationMs:l}),!i&&!c.ok)break}else{const t=chunkArray(s,c);for(let n=0;n<t.length;n++){const s=t[n],a=n*c;r.update(`Processing chunk ${n+1}/${t.length}...`,n/t.length*100);const i=await Promise.all(s.map(async(t,r)=>{const n=a+r,s=Date.now();return{index:n,result:await e.receive(t,o),durationMs:Date.now()-s}}));u.push(...i)}}return r.complete(),createSummary(u,Date.now()-n)}async function batchRegistryOps(e,t){const r=new ux_helpers_1.ProgressReporter(t.onProgress),n=Date.now(),{operations:s,atomic:o=!1,strategy:a="parallel",concurrency:c=5}=t;r.start(`Executing ${s.length} registry operations (${o?"atomic":"best-effort"} mode)...`);const i=[];if(o&&r.update("Warning: Atomic mode not fully implemented - using best-effort",10),"sequential"===a)for(let t=0;t<s.length;t++){const n=s[t],a=Date.now();r.update(`Operation ${t+1}/${s.length}: ${n.type} ${n.did}`,t/s.length*100);const c=await executeRegistryOperation(e,n),u=Date.now()-a;if(i.push({index:t,result:c,durationMs:u}),o&&!c.ok)break}else{const t=chunkArray(s,c);for(let n=0;n<t.length;n++){const s=t[n],a=n*c;r.update(`Processing chunk ${n+1}/${t.length}...`,n/t.length*100);const u=await Promise.all(s.map(async(t,r)=>{const n=a+r,s=Date.now();return{index:n,result:await executeRegistryOperation(e,t),durationMs:Date.now()-s}}));if(i.push(...u),o&&u.some(e=>!e.result.ok))break}}return r.complete(),createSummary(i,Date.now()-n)}async function batchResolve(e,t,r){const n=new ux_helpers_1.ProgressReporter(r?.onProgress),s=Date.now(),o=r?.concurrency??10;n.start(`Resolving ${t.length} DIDs...`);const a=[],c=chunkArray(t,o);for(let t=0;t<c.length;t++){const r=c[t],s=t*o;n.update(`Resolving chunk ${t+1}/${c.length}...`,t/c.length*100);const i=await Promise.all(r.map(async(t,r)=>{const n=s+r,o=Date.now();return{index:n,result:await e.resolve(t),durationMs:Date.now()-o}}));a.push(...i)}return n.complete(),createSummary(a,Date.now()-s)}async function batchGetEntries(e,t,r){const n=new ux_helpers_1.ProgressReporter(r?.onProgress),s=Date.now(),o=r?.concurrency??10;n.start(`Fetching ${t.length} registry entries...`);const a=[],c=chunkArray(t,o);for(let t=0;t<c.length;t++){const r=c[t],s=t*o;n.update(`Fetching chunk ${t+1}/${c.length}...`,t/c.length*100);const i=await Promise.all(r.map(async(t,r)=>{const n=s+r,o=Date.now();return{index:n,result:await e.getEntry(t),durationMs:Date.now()-o}}));a.push(...i)}return n.complete(),createSummary(a,Date.now()-s)}async function executeRegistryOperation(e,t){switch(t.type){case"register":{if(!t.params)return(0,shared_1.err)("INVALID_PARAMS");const{publicKey:r,name:n,scopes:s,x25519PublicKey:o,mlKemPublicKey:a,mlDsaPublicKey:c,xchange:i,receiveScopes:u,sdkVersion:l,minEnvelopeVersion:h,maxEnvelopeVersion:p,ttlMs:g}=t.params;return e.register(t.did,r,n,s,o,a,c,i,u,l,h,p,g)}case"revoke":return e.revoke(t.did);case"updateScopes":return t.newScopes&&"updateScopes"in e&&"function"==typeof e.updateScopes?e.updateScopes(t.did,t.newScopes):(0,shared_1.err)("INVALID_PARAMS");default:return(0,shared_1.err)("INVALID_OPERATION")}}function createSummary(e,t){const r=e.filter(e=>e.result.ok).length,n=e.filter(e=>!e.result.ok).length,s=e.length>0?e.reduce((e,t)=>e+t.durationMs,0)/e.length:0;return{total:e.length,succeeded:r,failed:n,results:e,totalDurationMs:t,avgDurationMs:s}}function chunkArray(e,t){const r=[];for(let n=0;n<e.length;n+=t)r.push(e.slice(n,n+t));return r}exports.BatchOperationError=BatchOperationError;
+"use strict";
+/**
+ * @module batch-operations
+ * Batch operations support for xBind - enhanced API efficiency
+ *
+ * Provides batch operations for:
+ * - Send: Multiple messages in one call (reduces round-trips)
+ * - Receive: Batch envelope processing
+ * - Registry: Bulk registration/revocation/updates
+ *
+ * Features:
+ * - Atomic semantics where possible (registry operations)
+ * - Partial success handling (graceful degradation)
+ * - Progress tracking for long-running batches
+ * - Performance optimization (parallel processing)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BatchOperationError = void 0;
+exports.batchSend = batchSend;
+exports.batchReceive = batchReceive;
+exports.batchRegistryOps = batchRegistryOps;
+exports.batchResolve = batchResolve;
+exports.batchGetEntries = batchGetEntries;
+const shared_1 = require("../_deps/shared/index.js");
+const ux_helpers_1 = require("../_deps/ux-helpers/index.js");
+/**
+ * Error thrown when batch operation fails.
+ */
+class BatchOperationError extends Error {
+    summary;
+    constructor(message, summary) {
+        super(message);
+        this.summary = summary;
+        this.name = 'BatchOperationError';
+    }
+}
+exports.BatchOperationError = BatchOperationError;
+/* ── Implementation ── */
+/**
+ * Batch send multiple messages.
+ *
+ * Performance optimization: Sends messages in parallel (default) or sequentially.
+ * Reduces round-trips for bulk message delivery.
+ *
+ * @param agent - Agent instance
+ * @param options - Batch send options
+ * @returns Batch summary with individual results
+ *
+ * @example
+ * ```typescript
+ * const agent = await Agent.create({ name: 'sender', registry });
+ * const summary = await batchSend(agent, {
+ *   messages: [
+ *     { to: 'did:key:abc', payload: { msg: 1 }, scope: 'chat' },
+ *     { to: 'did:key:def', payload: { msg: 2 }, scope: 'chat' },
+ *   ],
+ *   strategy: 'parallel',
+ * });
+ * console.log(`Sent ${summary.succeeded}/${summary.total} messages`);
+ * ```
+ */
+async function batchSend(agent, options) {
+    const progress = new ux_helpers_1.ProgressReporter(options.onProgress);
+    const startTime = Date.now();
+    const { messages, strategy = 'parallel', concurrency = 10, continueOnError = true, } = options;
+    progress.start(`Sending ${messages.length} messages (${strategy} mode)...`);
+    const results = [];
+    if (strategy === 'sequential') {
+        // Sequential: preserve ordering
+        for (let i = 0; i < messages.length; i++) {
+            const msg = messages[i];
+            const opStart = Date.now();
+            progress.update(`Sending message ${i + 1}/${messages.length}...`, (i / messages.length) * 100);
+            const result = await agent.send(msg);
+            const durationMs = Date.now() - opStart;
+            results.push({ index: i, result, durationMs });
+            if (!continueOnError && !result.ok) {
+                break;
+            }
+        }
+    }
+    else if (strategy === 'failfast') {
+        // Parallel with fail-fast: stop immediately on first error
+        const promises = messages.map((msg, index) => {
+            const opStart = Date.now();
+            return agent.send(msg).then(result => {
+                const durationMs = Date.now() - opStart;
+                if (!result.ok) {
+                    throw new BatchOperationError(`Batch send failed at index ${index}: ${result.error}`, createSummary(results, Date.now() - startTime));
+                }
+                return { index, result, durationMs };
+            });
+        });
+        try {
+            const allResults = await Promise.all(promises);
+            results.push(...allResults);
+        }
+        catch (error) {
+            if (error instanceof BatchOperationError) {
+                throw error;
+            }
+            throw new BatchOperationError('Batch send failed', createSummary(results, Date.now() - startTime));
+        }
+    }
+    else {
+        // Parallel: process concurrently with controlled concurrency
+        const chunks = chunkArray(messages, concurrency);
+        for (let chunkIndex = 0; chunkIndex < chunks.length; chunkIndex++) {
+            const chunk = chunks[chunkIndex];
+            const baseIndex = chunkIndex * concurrency;
+            progress.update(`Processing chunk ${chunkIndex + 1}/${chunks.length}...`, (chunkIndex / chunks.length) * 100);
+            const chunkResults = await Promise.all(chunk.map(async (msg, offset) => {
+                const index = baseIndex + offset;
+                const opStart = Date.now();
+                const result = await agent.send(msg);
+                const durationMs = Date.now() - opStart;
+                return { index, result, durationMs };
+            }));
+            results.push(...chunkResults);
+        }
+    }
+    progress.complete();
+    return createSummary(results, Date.now() - startTime);
+}
+/**
+ * Batch receive multiple envelopes.
+ *
+ * Performance optimization: Processes envelopes in parallel (default).
+ * Useful for bulk message ingestion from queues or webhooks.
+ *
+ * @param agent - Agent instance
+ * @param options - Batch receive options
+ * @returns Batch summary with individual results
+ *
+ * @example
+ * ```typescript
+ * const agent = await Agent.create({ name: 'receiver', registry });
+ * const summary = await batchReceive(agent, {
+ *   envelopes: incomingEnvelopes,
+ *   strategy: 'parallel',
+ * });
+ * console.log(`Processed ${summary.succeeded}/${summary.total} envelopes`);
+ * ```
+ */
+async function batchReceive(agent, options) {
+    const progress = new ux_helpers_1.ProgressReporter(options.onProgress);
+    const startTime = Date.now();
+    const { envelopes, receiveOptions, strategy = 'parallel', concurrency = 10, continueOnError = true, } = options;
+    progress.start(`Receiving ${envelopes.length} envelopes (${strategy} mode)...`);
+    const results = [];
+    if (strategy === 'sequential') {
+        // Sequential: preserve ordering
+        for (let i = 0; i < envelopes.length; i++) {
+            const envelope = envelopes[i];
+            const opStart = Date.now();
+            progress.update(`Receiving envelope ${i + 1}/${envelopes.length}...`, (i / envelopes.length) * 100);
+            const result = await agent.receive(envelope, receiveOptions);
+            const durationMs = Date.now() - opStart;
+            results.push({ index: i, result, durationMs });
+            if (!continueOnError && !result.ok) {
+                break;
+            }
+        }
+    }
+    else {
+        // Parallel: process concurrently with controlled concurrency
+        const chunks = chunkArray(envelopes, concurrency);
+        for (let chunkIndex = 0; chunkIndex < chunks.length; chunkIndex++) {
+            const chunk = chunks[chunkIndex];
+            const baseIndex = chunkIndex * concurrency;
+            progress.update(`Processing chunk ${chunkIndex + 1}/${chunks.length}...`, (chunkIndex / chunks.length) * 100);
+            const chunkResults = await Promise.all(chunk.map(async (envelope, offset) => {
+                const index = baseIndex + offset;
+                const opStart = Date.now();
+                const result = await agent.receive(envelope, receiveOptions);
+                const durationMs = Date.now() - opStart;
+                return { index, result, durationMs };
+            }));
+            results.push(...chunkResults);
+        }
+    }
+    progress.complete();
+    return createSummary(results, Date.now() - startTime);
+}
+/**
+ * Batch registry operations (register, revoke, updateScopes).
+ *
+ * Performance optimization: Groups operations by type for efficient processing.
+ * Atomic semantics: When atomic=true, all operations succeed or all fail.
+ *
+ * @param registry - Trust registry instance
+ * @param options - Batch registry options
+ * @returns Batch summary with individual results
+ *
+ * @example
+ * ```typescript
+ * const summary = await batchRegistryOps(registry, {
+ *   operations: [
+ *     { type: 'register', did: 'did:key:abc', params: { publicKey, name: 'Alice' } },
+ *     { type: 'revoke', did: 'did:key:old' },
+ *   ],
+ *   atomic: false, // best-effort mode
+ * });
+ * console.log(`Completed ${summary.succeeded}/${summary.total} operations`);
+ * ```
+ */
+async function batchRegistryOps(registry, options) {
+    const progress = new ux_helpers_1.ProgressReporter(options.onProgress);
+    const startTime = Date.now();
+    const { operations, atomic = false, strategy = 'parallel', concurrency = 5, } = options;
+    progress.start(`Executing ${operations.length} registry operations (${atomic ? 'atomic' : 'best-effort'} mode)...`);
+    const results = [];
+    // Atomic mode: execute all or rollback (not implemented in base TrustRegistry)
+    // This is a placeholder for future transaction support
+    if (atomic) {
+        progress.update('Warning: Atomic mode not fully implemented - using best-effort', 10);
+    }
+    if (strategy === 'sequential') {
+        // Sequential: preserve ordering
+        for (let i = 0; i < operations.length; i++) {
+            const op = operations[i];
+            const opStart = Date.now();
+            progress.update(`Operation ${i + 1}/${operations.length}: ${op.type} ${op.did}`, (i / operations.length) * 100);
+            const result = await executeRegistryOperation(registry, op);
+            const durationMs = Date.now() - opStart;
+            results.push({ index: i, result, durationMs });
+            if (atomic && !result.ok) {
+                // TODO: Rollback previous operations
+                break;
+            }
+        }
+    }
+    else {
+        // Parallel: process concurrently with controlled concurrency
+        const chunks = chunkArray(operations, concurrency);
+        for (let chunkIndex = 0; chunkIndex < chunks.length; chunkIndex++) {
+            const chunk = chunks[chunkIndex];
+            const baseIndex = chunkIndex * concurrency;
+            progress.update(`Processing chunk ${chunkIndex + 1}/${chunks.length}...`, (chunkIndex / chunks.length) * 100);
+            const chunkResults = await Promise.all(chunk.map(async (op, offset) => {
+                const index = baseIndex + offset;
+                const opStart = Date.now();
+                const result = await executeRegistryOperation(registry, op);
+                const durationMs = Date.now() - opStart;
+                return { index, result, durationMs };
+            }));
+            results.push(...chunkResults);
+            if (atomic && chunkResults.some(r => !r.result.ok)) {
+                // TODO: Rollback all operations
+                break;
+            }
+        }
+    }
+    progress.complete();
+    return createSummary(results, Date.now() - startTime);
+}
+/**
+ * Batch resolve multiple DIDs.
+ *
+ * Performance optimization: Resolves DIDs in parallel.
+ * Useful for resolving recipient keys before bulk message sending.
+ *
+ * @param registry - Trust registry instance
+ * @param dids - DIDs to resolve
+ * @param options - Optional progress callback and concurrency
+ * @returns Batch summary with resolution results
+ *
+ * @example
+ * ```typescript
+ * const summary = await batchResolve(registry, [
+ *   'did:key:abc',
+ *   'did:key:def',
+ *   'did:key:ghi',
+ * ]);
+ * const keys = summary.results
+ *   .filter(r => r.result.ok)
+ *   .map(r => r.result.value);
+ * ```
+ */
+async function batchResolve(registry, dids, options) {
+    const progress = new ux_helpers_1.ProgressReporter(options?.onProgress);
+    const startTime = Date.now();
+    const concurrency = options?.concurrency ?? 10;
+    progress.start(`Resolving ${dids.length} DIDs...`);
+    const results = [];
+    const chunks = chunkArray(dids, concurrency);
+    for (let chunkIndex = 0; chunkIndex < chunks.length; chunkIndex++) {
+        const chunk = chunks[chunkIndex];
+        const baseIndex = chunkIndex * concurrency;
+        progress.update(`Resolving chunk ${chunkIndex + 1}/${chunks.length}...`, (chunkIndex / chunks.length) * 100);
+        const chunkResults = await Promise.all(chunk.map(async (did, offset) => {
+            const index = baseIndex + offset;
+            const opStart = Date.now();
+            const result = await registry.resolve(did);
+            const durationMs = Date.now() - opStart;
+            return { index, result, durationMs };
+        }));
+        results.push(...chunkResults);
+    }
+    progress.complete();
+    return createSummary(results, Date.now() - startTime);
+}
+/**
+ * Batch get registry entries.
+ *
+ * Performance optimization: Fetches entries in parallel.
+ * Returns full registry metadata for multiple DIDs.
+ *
+ * @param registry - Trust registry instance
+ * @param dids - DIDs to fetch
+ * @param options - Optional progress callback and concurrency
+ * @returns Batch summary with entry results
+ *
+ * @example
+ * ```typescript
+ * const summary = await batchGetEntries(registry, dids);
+ * const entries = summary.results
+ *   .filter(r => r.result.ok)
+ *   .map(r => r.result.value);
+ * ```
+ */
+async function batchGetEntries(registry, dids, options) {
+    const progress = new ux_helpers_1.ProgressReporter(options?.onProgress);
+    const startTime = Date.now();
+    const concurrency = options?.concurrency ?? 10;
+    progress.start(`Fetching ${dids.length} registry entries...`);
+    const results = [];
+    const chunks = chunkArray(dids, concurrency);
+    for (let chunkIndex = 0; chunkIndex < chunks.length; chunkIndex++) {
+        const chunk = chunks[chunkIndex];
+        const baseIndex = chunkIndex * concurrency;
+        progress.update(`Fetching chunk ${chunkIndex + 1}/${chunks.length}...`, (chunkIndex / chunks.length) * 100);
+        const chunkResults = await Promise.all(chunk.map(async (did, offset) => {
+            const index = baseIndex + offset;
+            const opStart = Date.now();
+            const result = await registry.getEntry(did);
+            const durationMs = Date.now() - opStart;
+            return { index, result, durationMs };
+        }));
+        results.push(...chunkResults);
+    }
+    progress.complete();
+    return createSummary(results, Date.now() - startTime);
+}
+/* ── Helper Functions ── */
+/**
+ * Execute a single registry operation.
+ */
+async function executeRegistryOperation(registry, op) {
+    switch (op.type) {
+        case 'register': {
+            if (!op.params) {
+                return (0, shared_1.err)('INVALID_PARAMS');
+            }
+            const { publicKey, name, scopes, x25519PublicKey, mlKemPublicKey, mlDsaPublicKey, xchange, receiveScopes, sdkVersion, minEnvelopeVersion, maxEnvelopeVersion, ttlMs } = op.params;
+            return registry.register(op.did, publicKey, name, scopes, x25519PublicKey, mlKemPublicKey, mlDsaPublicKey, xchange, receiveScopes, sdkVersion, minEnvelopeVersion, maxEnvelopeVersion, ttlMs);
+        }
+        case 'revoke':
+            return registry.revoke(op.did);
+        case 'updateScopes': {
+            if (!op.newScopes || !('updateScopes' in registry) || typeof registry.updateScopes !== 'function') {
+                return (0, shared_1.err)('INVALID_PARAMS');
+            }
+            return registry.updateScopes(op.did, op.newScopes);
+        }
+        default:
+            return (0, shared_1.err)('INVALID_OPERATION');
+    }
+}
+/**
+ * Create batch summary from results.
+ */
+function createSummary(results, totalDurationMs) {
+    const succeeded = results.filter(r => r.result.ok).length;
+    const failed = results.filter(r => !r.result.ok).length;
+    const avgDurationMs = results.length > 0
+        ? results.reduce((sum, r) => sum + r.durationMs, 0) / results.length
+        : 0;
+    return {
+        total: results.length,
+        succeeded,
+        failed,
+        results,
+        totalDurationMs,
+        avgDurationMs,
+    };
+}
+/**
+ * Split array into chunks of specified size.
+ */
+function chunkArray(array, size) {
+    const chunks = [];
+    for (let i = 0; i < array.length; i += size) {
+        chunks.push(array.slice(i, i + size));
+    }
+    return chunks;
+}