@private.me/xbind 3.0.0 → 3.0.2

package/dist-standalone/batch-operations.js

@@ -1 +1,388 @@
-import{err}from"./_deps/shared/index.js";import{ProgressReporter}from"./_deps/ux-helpers/index.js";export class BatchOperationError extends Error{summary;constructor(e,t){super(e),this.summary=t,this.name="BatchOperationError"}}export async function batchSend(e,t){const n=new ProgressReporter(t.onProgress),r=Date.now(),{messages:o,strategy:s="parallel",concurrency:a=10,continueOnError:c=!0}=t;n.start(`Sending ${o.length} messages (${s} mode)...`);const i=[];if("sequential"===s)for(let t=0;t<o.length;t++){const r=o[t],s=Date.now();n.update(`Sending message ${t+1}/${o.length}...`,t/o.length*100);const a=await e.send(r),u=Date.now()-s;if(i.push({index:t,result:a,durationMs:u}),!c&&!a.ok)break}else if("failfast"===s){const t=o.map((t,n)=>{const o=Date.now();return e.send(t).then(e=>{const t=Date.now()-o;if(!e.ok)throw new BatchOperationError(`Batch send failed at index ${n}: ${e.error}`,createSummary(i,Date.now()-r));return{index:n,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()-r))}}else{const t=chunkArray(o,a);for(let r=0;r<t.length;r++){const o=t[r],s=r*a;n.update(`Processing chunk ${r+1}/${t.length}...`,r/t.length*100);const c=await Promise.all(o.map(async(t,n)=>{const r=s+n,o=Date.now();return{index:r,result:await e.send(t),durationMs:Date.now()-o}}));i.push(...c)}}return n.complete(),createSummary(i,Date.now()-r)}export async function batchReceive(e,t){const n=new ProgressReporter(t.onProgress),r=Date.now(),{envelopes:o,receiveOptions:s,strategy:a="parallel",concurrency:c=10,continueOnError:i=!0}=t;n.start(`Receiving ${o.length} envelopes (${a} mode)...`);const u=[];if("sequential"===a)for(let t=0;t<o.length;t++){const r=o[t],a=Date.now();n.update(`Receiving envelope ${t+1}/${o.length}...`,t/o.length*100);const c=await e.receive(r,s),l=Date.now()-a;if(u.push({index:t,result:c,durationMs:l}),!i&&!c.ok)break}else{const t=chunkArray(o,c);for(let r=0;r<t.length;r++){const o=t[r],a=r*c;n.update(`Processing chunk ${r+1}/${t.length}...`,r/t.length*100);const i=await Promise.all(o.map(async(t,n)=>{const r=a+n,o=Date.now();return{index:r,result:await e.receive(t,s),durationMs:Date.now()-o}}));u.push(...i)}}return n.complete(),createSummary(u,Date.now()-r)}export async function batchRegistryOps(e,t){const n=new ProgressReporter(t.onProgress),r=Date.now(),{operations:o,atomic:s=!1,strategy:a="parallel",concurrency:c=5}=t;n.start(`Executing ${o.length} registry operations (${s?"atomic":"best-effort"} mode)...`);const i=[];if(s&&n.update("Warning: Atomic mode not fully implemented - using best-effort",10),"sequential"===a)for(let t=0;t<o.length;t++){const r=o[t],a=Date.now();n.update(`Operation ${t+1}/${o.length}: ${r.type} ${r.did}`,t/o.length*100);const c=await executeRegistryOperation(e,r),u=Date.now()-a;if(i.push({index:t,result:c,durationMs:u}),s&&!c.ok)break}else{const t=chunkArray(o,c);for(let r=0;r<t.length;r++){const o=t[r],a=r*c;n.update(`Processing chunk ${r+1}/${t.length}...`,r/t.length*100);const u=await Promise.all(o.map(async(t,n)=>{const r=a+n,o=Date.now();return{index:r,result:await executeRegistryOperation(e,t),durationMs:Date.now()-o}}));if(i.push(...u),s&&u.some(e=>!e.result.ok))break}}return n.complete(),createSummary(i,Date.now()-r)}export async function batchResolve(e,t,n){const r=new ProgressReporter(n?.onProgress),o=Date.now(),s=n?.concurrency??10;r.start(`Resolving ${t.length} DIDs...`);const a=[],c=chunkArray(t,s);for(let t=0;t<c.length;t++){const n=c[t],o=t*s;r.update(`Resolving chunk ${t+1}/${c.length}...`,t/c.length*100);const i=await Promise.all(n.map(async(t,n)=>{const r=o+n,s=Date.now();return{index:r,result:await e.resolve(t),durationMs:Date.now()-s}}));a.push(...i)}return r.complete(),createSummary(a,Date.now()-o)}export async function batchGetEntries(e,t,n){const r=new ProgressReporter(n?.onProgress),o=Date.now(),s=n?.concurrency??10;r.start(`Fetching ${t.length} registry entries...`);const a=[],c=chunkArray(t,s);for(let t=0;t<c.length;t++){const n=c[t],o=t*s;r.update(`Fetching chunk ${t+1}/${c.length}...`,t/c.length*100);const i=await Promise.all(n.map(async(t,n)=>{const r=o+n,s=Date.now();return{index:r,result:await e.getEntry(t),durationMs:Date.now()-s}}));a.push(...i)}return r.complete(),createSummary(a,Date.now()-o)}async function executeRegistryOperation(e,t){switch(t.type){case"register":{if(!t.params)return err("INVALID_PARAMS");const{publicKey:n,name:r,scopes:o,x25519PublicKey:s,mlKemPublicKey:a,mlDsaPublicKey:c,xchange:i,receiveScopes:u,sdkVersion:l,minEnvelopeVersion:p,maxEnvelopeVersion:h,ttlMs:g}=t.params;return e.register(t.did,n,r,o,s,a,c,i,u,l,p,h,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):err("INVALID_PARAMS");default:return err("INVALID_OPERATION")}}function createSummary(e,t){const n=e.filter(e=>e.result.ok).length,r=e.filter(e=>!e.result.ok).length,o=e.length>0?e.reduce((e,t)=>e+t.durationMs,0)/e.length:0;return{total:e.length,succeeded:n,failed:r,results:e,totalDurationMs:t,avgDurationMs:o}}function chunkArray(e,t){const n=[];for(let r=0;r<e.length;r+=t)n.push(e.slice(r,r+t));return n}
+/**
+ * @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)
+ */
+import { err } from"./_deps/shared/index.js";
+import { ProgressReporter } from"./_deps/ux-helpers/index.js";
+/**
+ * Error thrown when batch operation fails.
+ */
+export class BatchOperationError extends Error {
+    summary;
+    constructor(message, summary) {
+        super(message);
+        this.summary = summary;
+        this.name = '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`);
+ * ```
+ */
+export async function batchSend(agent, options) {
+    const progress = new 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`);
+ * ```
+ */
+export async function batchReceive(agent, options) {
+    const progress = new 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`);
+ * ```
+ */
+export async function batchRegistryOps(registry, options) {
+    const progress = new 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);
+ * ```
+ */
+export async function batchResolve(registry, dids, options) {
+    const progress = new 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);
+ * ```
+ */
+export async function batchGetEntries(registry, dids, options) {
+    const progress = new 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 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 err('INVALID_PARAMS');
+            }
+            return registry.updateScopes(op.did, op.newScopes);
+        }
+        default:
+            return 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;
+}