@private.me/xbind 3.0.2 → 3.0.3

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

@@ -1,397 +1 @@
-"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;
-}
+"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;