@private.me/xbind 3.0.2 → 3.0.3

package/dist-standalone/batch-operations.js

@@ -1,388 +1 @@
-/**
- * @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;
-}
+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}