@spine-event-engine/server 2.0.0-snapshot.2

package/dist/context/projection-handoff.js

@@ -0,0 +1,172 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+var _a;
+import { Delivery } from "../delivery/delivery.js";
+import { ShardIndex } from "../delivery/shard-index.js";
+import { DeliveryReadiness, InboxHandoff, } from "./local-inbox-handoff.js";
+const projectionLabels = ["UPDATE_SUBSCRIBER"];
+/**
+ * Persists and replays delivery rows for projection subscribers.
+ */
+export class LocalProjectionInbox {
+    #contextName;
+    #targets = new Map();
+    #endpoints = new Map();
+    #readiness;
+    #keepTenant;
+    #inFlightHandoffs = new Map();
+    #inFlightMessageIds = new Set();
+    #acknowledgedMessageIds = new Set();
+    #nextVersion = 0n;
+    /**
+     * Creates a local projection inbox.
+     * @param contextName Names the bounded context that owns this inbox.
+     * @param readiness Coordinates delivery readiness after persistence.
+     * @param keepTenant Records a tenant before its message is persisted.
+     */
+    constructor(contextName, readiness = new DeliveryReadiness(), keepTenant = () => Promise.resolve()) {
+        this.#contextName = contextName;
+        this.#readiness =
+            readiness instanceof DeliveryReadiness ? readiness : new DeliveryReadiness(readiness);
+        this.#keepTenant = keepTenant;
+    }
+    /**
+     * Registers a target that replays projection messages.
+     * @param target Handles messages for one projection type.
+     */
+    register(target) {
+        this.#targets.set(target.targetTypeUrl, target);
+        this.#endpoints.set(target.targetTypeUrl, Object.freeze([
+            InboxHandoff.endpoint({
+                label: projectionLabels[0],
+                inboxId: { targetTypeUrl: target.targetTypeUrl },
+                shard: ShardIndex.single(),
+            }),
+        ]));
+    }
+    /**
+     * Lists endpoints registered for projection delivery.
+     * @returns Returns immutable endpoint descriptions.
+     */
+    endpoints() {
+        return Object.freeze([...this.#endpoints.values()].flat());
+    }
+    /**
+     * Dispatches a durable inbox row through its projection target.
+     * @param message Contains the persisted inbox row to replay.
+     * @param deliveryTenantId Identifies the tenant that owns the row when present.
+     * @returns A promise that resolves after the inbox row is replayed.
+     */
+    replay(message, deliveryTenantId) {
+        return this.#replay(message, deliveryTenantId);
+    }
+    /**
+     * Persists and drains one projection inbox message.
+     * @param delivery Stores and drains the inbox row.
+     * @param input Describes the message to persist.
+     * @param deliveryTenantId Identifies the tenant that owns the message when present.
+     * @returns Resolves to the persisted inbox row.
+     */
+    async receive(delivery, input, deliveryTenantId) {
+        const routed = this.#readiness.route(delivery);
+        return await InboxHandoff.coordinate({
+            handoffs: this.#inFlightHandoffs,
+            key: InboxHandoff.key(input, deliveryTenantId),
+            onHandoff: () => this.#receiveAndDrain(routed, input, deliveryTenantId),
+        });
+    }
+    async #receiveAndDrain(delivery, input, deliveryTenantId) {
+        if (deliveryTenantId !== undefined) {
+            await this.#keepTenant(deliveryTenantId);
+        }
+        const written = await delivery.inbox.receive({
+            inboxId: input.inboxId,
+            signalId: input.signalId,
+            label: input.label,
+            status: input.status,
+            shard: input.shard,
+            whenReceived: new Date(),
+            version: this.#takeVersion(),
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+            ...(input.keepUntil === undefined ? {} : { keepUntil: input.keepUntil }),
+        });
+        const endpoint = written.outcome === "WRITTEN"
+            ? InboxHandoff.configuredEndpoint(written.message, this.#endpoints.get(written.message.inboxId.targetTypeUrl) ?? [])
+            : undefined;
+        this.#trackMessage(written.message);
+        try {
+            await this.#readiness
+                .claim(endpoint === undefined ? undefined : InboxHandoff.ready(endpoint, deliveryTenantId))
+                .complete(() => this.#isAcknowledged(written.message)
+                ? Promise.resolve()
+                : InboxHandoff.drain({
+                    delivery,
+                    received: written.message,
+                    node: this.#contextName,
+                    onReplay: (message) => this.#replay(message, deliveryTenantId),
+                    acceptMessage: (message) => InboxHandoff.sameMessageId(message.id, written.message.id) ||
+                        (message.label === "UPDATE_SUBSCRIBER" &&
+                            this.#targets.has(message.inboxId.targetTypeUrl)),
+                    onAcknowledged: (message) => {
+                        this.#recordAcknowledgement(message);
+                    },
+                    replayFailureMessage: "Projection inbox replay failed.",
+                    skippedMessage: "Projection inbox delivery was skipped before the target row was delivered.",
+                    unfinishedMessage: "Projection inbox delivery did not reach the target row before the local drain finished.",
+                }));
+            return written.message;
+        }
+        finally {
+            this.#untrackMessage(written.message);
+        }
+    }
+    #trackMessage(message) {
+        this.#inFlightMessageIds.add(InboxHandoff.messageIdKey(message));
+    }
+    #untrackMessage(message) {
+        const key = InboxHandoff.messageIdKey(message);
+        this.#inFlightMessageIds.delete(key);
+        this.#acknowledgedMessageIds.delete(key);
+    }
+    #recordAcknowledgement(message) {
+        const key = InboxHandoff.messageIdKey(message);
+        if (this.#inFlightMessageIds.has(key))
+            this.#acknowledgedMessageIds.add(key);
+    }
+    #isAcknowledged(message) {
+        return this.#acknowledgedMessageIds.has(InboxHandoff.messageIdKey(message));
+    }
+    #takeVersion() {
+        this.#nextVersion += 1n;
+        return this.#nextVersion;
+    }
+    async #replay(message, deliveryTenantId) {
+        _a.#assert(message);
+        const target = this.#targets.get(message.inboxId.targetTypeUrl);
+        if (target === undefined) {
+            throw new Error(`BoundedContext delivery has no projection subscriber target for "${message.inboxId.targetTypeUrl}".`);
+        }
+        await target.replay(message, deliveryTenantId);
+    }
+    static #assert(message) {
+        if (message.label !== "UPDATE_SUBSCRIBER") {
+            throw new Error(`BoundedContext delivery has no handler for inbox label "${message.label}".`);
+        }
+        if (message.status !== "TO_DELIVER") {
+            throw new Error(`BoundedContext delivery cannot replay projection inbox message with status "${message.status}".`);
+        }
+    }
+}
+_a = LocalProjectionInbox;
+//# sourceMappingURL=projection-handoff.js.map

package/dist/context/projection-handoff.js.map

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

package/dist/context/tenant-index.d.ts

@@ -0,0 +1,41 @@
+import type { TenantId } from "@spine-event-engine/proto";
+import { type StorageFactory } from "@spine-event-engine/storage";
+type TenantMode = "single-tenant" | "multitenant";
+/**
+ * Tracks tenants admitted through one factory-owned provider catalog.
+ */
+export interface TenantIndex {
+    /**
+     * Identifies whether the owning context accepts tenant IDs.
+     */
+    readonly tenantMode: TenantMode;
+    /**
+     * Lists complete tenants discovered by the provider.
+     *
+     * @returns The provider-owned tenant IDs.
+     */
+    all(): Promise<readonly TenantId[]>;
+    /**
+     * Records one complete tenant through provider-native catalog state.
+     *
+     * @param tenantId The complete generated tenant ID.
+     * @returns Completion of provider catalog admission.
+     */
+    keep(tenantId: TenantId): Promise<void>;
+    /**
+     * Closes this context view without closing the factory-owned catalog.
+     */
+    close(): void;
+}
+/**
+ * Creates context views over factory-owned tenant catalogs.
+ */
+export declare const TenantIndexes: Readonly<{
+    create(input: {
+        readonly contextName: string;
+        readonly tenantMode: TenantMode;
+        readonly storageFactory: StorageFactory;
+    }): TenantIndex;
+}>;
+export {};
+//# sourceMappingURL=tenant-index.d.ts.map

package/dist/context/tenant-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-index.d.ts","sourceRoot":"","sources":["../../src/context/tenant-index.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAMlF,KAAK,UAAU,GAAG,eAAe,GAAG,aAAa,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,WAAW;IAG1B;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAEhC;;;;OAIG;IACH,GAAG,IAAI,OAAO,CAAC,SAAS,QAAQ,EAAE,CAAC,CAAC;IAEpC;;;;;OAKG;IACH,IAAI,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExC;;OAEG;IACH,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,QAAQ,CAAC;IACnC,MAAM,CAAC,KAAK,EAAE;QACZ,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;QAChC,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;KACzC,GAAG,WAAW,CAAC;CACjB,CAcC,CAAC"}

package/dist/context/tenant-index.js

@@ -0,0 +1,92 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import { TenantBoundary } from "@spine-event-engine/storage";
+/**
+ * Creates context views over factory-owned tenant catalogs.
+ */
+export const TenantIndexes = Object.freeze({
+    // prettier-ignore
+    /**
+     * Creates an index view for one context.
+     *
+     * @param input Identifies the diagnostic context, tenancy mode, and factory.
+     * @returns The matching tenant index.
+     */
+    create(input) {
+        return input.tenantMode === "single-tenant"
+            ? new SingleTenantIndex(input.contextName)
+            : new StorageTenantIndex(input.contextName, tenantCatalog(input.storageFactory));
+    },
+});
+class SingleTenantIndex {
+    contextName;
+    tenantMode = "single-tenant";
+    #open = true;
+    constructor(contextName) {
+        this.contextName = contextName;
+    }
+    all() {
+        const closed = this.closedError();
+        return closed === undefined ? Promise.resolve(Object.freeze([])) : Promise.reject(closed);
+    }
+    keep() {
+        const closed = this.closedError();
+        return Promise.reject(closed ??
+            new Error(`Single-tenant context "${this.contextName}" does not accept tenant recording.`));
+    }
+    close() {
+        this.#open = false;
+    }
+    closedError() {
+        return this.#open ? undefined : new Error("TenantIndex is closed.");
+    }
+}
+class StorageTenantIndex {
+    contextName;
+    catalog;
+    tenantMode = "multitenant";
+    #open = true;
+    constructor(contextName, catalog) {
+        this.contextName = contextName;
+        this.catalog = catalog;
+    }
+    async all() {
+        this.requireOpen();
+        return Object.freeze((await this.catalog.all()).map((boundary) => {
+            if (boundary.single || boundary.tenantId === undefined)
+                throw new Error("Multitenant provider catalog returned a single-tenant boundary.");
+            return boundary.tenantId;
+        }));
+    }
+    keep(tenantId) {
+        return Promise.resolve().then(() => {
+            this.requireOpen();
+            return this.catalog.keep(TenantBoundary.from(tenantId));
+        });
+    }
+    close() {
+        this.#open = false;
+    }
+    requireOpen() {
+        if (!this.#open)
+            throw new Error(`TenantIndex for "${this.contextName}" is closed.`);
+    }
+}
+function tenantCatalog(factory) {
+    const provider = factory;
+    if (typeof provider.tenantCatalog !== "function")
+        throw new Error("Multitenant storage requires a provider-owned tenant catalog.");
+    return provider.tenantCatalog();
+}
+//# sourceMappingURL=tenant-index.js.map

package/dist/context/tenant-index.js.map

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

package/dist/delivery/conditional-pickup.d.ts

@@ -0,0 +1,25 @@
+import type { DeliveryOperationOptions, DeliveryWorkRegistry, DeliveryWorkSession } from "./delivery-ports.js";
+import type { WorkerId } from "@spine-event-engine/proto/delivery";
+import type { ShardIndex } from "./shard-index.js";
+type OnConditionalPickUp = (shard: ShardIndex, worker: WorkerId, options?: DeliveryOperationOptions) => Promise<DeliveryWorkSession | undefined>;
+/**
+ * Provides framework-private conditional pickup for registries that support it.
+ */
+export declare const conditionalPickUp: Readonly<{
+    /**
+     * Records a registry's conditional pickup implementation.
+     *
+     * @param registry Identifies the supporting work registry.
+     * @param pickUp Acquires only when remote pending work exists.
+     */
+    register: (registry: DeliveryWorkRegistry, pickUp: OnConditionalPickUp) => void;
+    /**
+     * Finds a registry's conditional pickup implementation.
+     *
+     * @param registry Identifies the work registry.
+     * @returns The conditional pickup when the registry supports it.
+     */
+    for: (registry: DeliveryWorkRegistry) => OnConditionalPickUp | undefined;
+}>;
+export {};
+//# sourceMappingURL=conditional-pickup.d.ts.map

package/dist/delivery/conditional-pickup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conditional-pickup.d.ts","sourceRoot":"","sources":["../../src/delivery/conditional-pickup.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EACV,wBAAwB,EACxB,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oCAAoC,CAAC;AACnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,KAAK,mBAAmB,GAAG,CACzB,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,QAAQ,EAChB,OAAO,CAAC,EAAE,wBAAwB,KAC/B,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAAC;AAG9C;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC;IAGvC;;;;;OAKG;IACH,QAAQ,EAAE,CAAC,QAAQ,EAAE,oBAAoB,EAAE,MAAM,EAAE,mBAAmB,KAAK,IAAI,CAAC;IAEhF;;;;;OAKG;IACH,GAAG,EAAE,CAAC,QAAQ,EAAE,oBAAoB,KAAK,mBAAmB,GAAG,SAAS,CAAC;CAC1E,CAOC,CAAC"}

package/dist/delivery/conditional-pickup.js

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+const pickups = new WeakMap();
+/**
+ * Provides framework-private conditional pickup for registries that support it.
+ */
+export const conditionalPickUp = Object.freeze({
+    register(registry, pickUp) {
+        pickups.set(registry, pickUp);
+    },
+    for(registry) {
+        return pickups.get(registry);
+    },
+});
+//# sourceMappingURL=conditional-pickup.js.map

package/dist/delivery/conditional-pickup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conditional-pickup.js","sourceRoot":"","sources":["../../src/delivery/conditional-pickup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAeH,MAAM,OAAO,GAAG,IAAI,OAAO,EAA6C,CAAC;AAEzE;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAkBzB,MAAM,CAAC,MAAM,CAAC;IACjB,QAAQ,CAAC,QAA8B,EAAE,MAA2B;QAClE,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAChC,CAAC;IACD,GAAG,CAAC,QAA8B;QAChC,OAAO,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC;CACF,CAAC,CAAC"}

package/dist/delivery/delivery-builder.d.ts

@@ -0,0 +1,216 @@
+import type { Any } from "@bufbuild/protobuf/wkt";
+import type { StorageContext, StorageFactory } from "@spine-event-engine/storage";
+import type { WorkerId } from "@spine-event-engine/proto/delivery";
+import { type OnDeliveryMessage } from "./delivery.js";
+import { DeliveryMonitor } from "./delivery-monitor.js";
+import type { DeliveryInbox, DeliveryWorkRegistry } from "./delivery-ports.js";
+import type { DeliveryControlledRun } from "./delivery-run-control.js";
+import { ShardIndex } from "./shard-index.js";
+/**
+ * Provides package-local controls for builder-created deliveries.
+ */
+export interface DeliveryControls {
+    /**
+     * Finds controlled execution for one builder-created delivery.
+     *
+     * @param delivery The builder-created delivery.
+     * @returns Its controlled runner, if present.
+     */
+    runner(delivery: Delivery): ((options: DeliveryControlledRun) => Promise<DeliveryResult>) | undefined;
+}
+/**
+ * Exposes package-local controls for builder-created deliveries.
+ */
+export declare const deliveryControls: DeliveryControls;
+/**
+ * Assigns inbox targets to durable delivery shards.
+ */
+export interface DeliveryStrategy {
+    /**
+     * Positive number of shards addressable by this strategy.
+     */
+    readonly shardCount: number;
+    /**
+     * Returns the shard for one canonical packed Entity ID and target type.
+     *
+     * The supplied `Any` contains the typed ID's type URL and bytes. Treat it as
+     * immutable typed identity, not as a display string.
+     *
+     * @param targetId The target identity.
+     * @param targetType The target type URL.
+     * @returns The durable shard for the target.
+     */
+    shardFor(targetId: Any, targetType: string): ShardIndex;
+}
+/**
+ * Places every target in one local shard.
+ */
+export declare class UniformAcrossAllShards implements DeliveryStrategy {
+    #private;
+    /**
+     * Returns a strategy with the requested positive number of shards.
+     *
+     * @param shards The number of addressable shards.
+     * @returns A uniform shard strategy.
+     */
+    static forNumber(shards: number): UniformAcrossAllShards;
+    /**
+     * Returns the shared single-shard strategy.
+     *
+     * @returns The shared single-shard strategy.
+     */
+    static singleShard(): UniformAcrossAllShards;
+    /**
+     * Number of uniformly distributed shards.
+     */
+    readonly shardCount: number;
+    private constructor();
+    /**
+     * Determines a stable shard from a target identity.
+     *
+     * @param targetId The target identity.
+     * @param targetType The target type URL.
+     * @returns The stable shard for the target.
+     */
+    shardFor(targetId: Any, targetType: string): ShardIndex;
+}
+export { DeliveryMonitor, type DeliveryStatistics } from "./delivery-monitor.js";
+/**
+ * Immutable outcome of one finite local delivery run.
+ */
+export interface DeliveryResult {
+    /**
+     * Terminal reason for this local run.
+     */
+    readonly status: "COMPLETED" | "SKIPPED" | "STOPPED" | "FAILED";
+}
+/**
+ * Options for one finite local delivery run.
+ */
+export interface DeliveryRunOptions {
+    /**
+     * Framework endpoint invoked for each available inbox row.
+     */
+    readonly onMessage: OnDeliveryMessage;
+    /**
+     * Shard to process; defaults to the strategy's only shard when applicable.
+     * An explicit shard's `ofTotal` must equal the strategy's resolved `shardCount`.
+     */
+    readonly shard?: ShardIndex;
+}
+/**
+ * Builder-owned public delivery view.
+ */
+export interface Delivery {
+    /**
+     * Immutable storage namespace selected for this delivery.
+     */
+    readonly context: StorageContext;
+    /**
+     * Storage factory selected for durable delivery records.
+     */
+    readonly storageFactory: StorageFactory;
+    /**
+     * Target-to-shard strategy selected for inbox writes and runs.
+     */
+    readonly strategy: DeliveryStrategy;
+    /**
+     * Node identity used for exclusive shard pickup.
+     */
+    readonly node: string;
+    /**
+     * Identifies the complete opaque worker used for shard ownership.
+     */
+    readonly worker: WorkerId;
+    /**
+     * Maximum accepted work per internal delivery page, from 1 through 1000.
+     */
+    readonly pageSize: number;
+    /**
+     * Durable inbox facade.
+     */
+    readonly inbox: DeliveryInbox;
+    /**
+     * Executes one finite local shard delivery.
+     *
+     * @param options The shard and endpoint callback.
+     * @returns The terminal finite-run result.
+     */
+    run(options: DeliveryRunOptions): Promise<DeliveryResult>;
+}
+/**
+ * Configures and snapshots one public {@link Delivery}.
+ */
+export declare class DeliveryBuilder {
+    #private;
+    /**
+     * Sets the storage namespace for Inbox and shard records.
+     *
+     * @param context The delivery storage namespace.
+     * @returns This builder.
+     */
+    withContext(context: StorageContext): this;
+    /**
+     * Sets the storage factory.
+     *
+     * @param storageFactory The durable storage factory.
+     * @returns This builder.
+     */
+    withStorageFactory(storageFactory: StorageFactory): this;
+    /**
+     * Sets the registry used for exclusive shard pickup.
+     *
+     * @param workRegistry The shard work registry.
+     * @returns This builder.
+     */
+    withWorkRegistry(workRegistry: DeliveryWorkRegistry): this;
+    /**
+     * Sets an inbox port instead of the local durable inbox default.
+     *
+     * @param inbox The inbox port.
+     * @returns This builder.
+     */
+    withInbox(inbox: DeliveryInbox): this;
+    /**
+     * Sets the target-to-shard strategy.
+     *
+     * @param strategy The target strategy.
+     * @returns This builder.
+     */
+    withStrategy(strategy: DeliveryStrategy): this;
+    /**
+     * Sets finite-run observation and cancellation.
+     *
+     * @param monitor The run monitor.
+     * @returns This builder.
+     */
+    withMonitor(monitor: DeliveryMonitor): this;
+    /**
+     * Sets the positive accepted-work bound for one page.
+     *
+     * @param pageSize The positive page size.
+     * @returns This builder.
+     */
+    withPageSize(pageSize: number): this;
+    /**
+     * Sets the node identity used for shard pickup.
+     *
+     * @param node The non-empty node identity.
+     * @returns This builder.
+     */
+    withNode(node: string): this;
+    /**
+     * Sets the complete opaque worker identity used for shard ownership.
+     *
+     * @param worker The generated worker identity for this delivery lifetime.
+     * @returns This builder.
+     */
+    withWorker(worker: WorkerId): this;
+    /**
+     * Creates one immutable delivery from the current builder configuration.
+     *
+     * @returns The configured delivery.
+     */
+    build(): Delivery;
+}
+//# sourceMappingURL=delivery-builder.d.ts.map

package/dist/delivery/delivery-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery-builder.d.ts","sourceRoot":"","sources":["../../src/delivery/delivery-builder.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAClF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oCAAoC,CAAC;AAGnE,OAAO,EAA4B,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACjF,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC/E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAa9C;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAG/B;;;;;OAKG;IACH,MAAM,CACJ,QAAQ,EAAE,QAAQ,GACjB,CAAC,CAAC,OAAO,EAAE,qBAAqB,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC,GAAG,SAAS,CAAC;CAC9E;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,gBAW7B,CAAC;AAEH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAG/B;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;;;;;;;;OASG;IACH,QAAQ,CAAC,QAAQ,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,GAAG,UAAU,CAAC;CACzD;AAED;;GAEG;AACH,qBAAa,sBAAuB,YAAW,gBAAgB;;IAG7D;;;;;OAKG;IACH,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,sBAAsB;IAIxD;;;;OAIG;IACH,MAAM,CAAC,WAAW,IAAI,sBAAsB;IAI5C;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,OAAO;IAQP;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,GAAG,UAAU;CAYxD;AAED,OAAO,EAAE,eAAe,EAAE,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEjF;;GAEG;AACH,MAAM,WAAW,cAAc;IAG7B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;CACjE;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAGjC;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IAEtC;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IAGvB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IAEjC;;OAEG;IACH,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IAExC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IAEpC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAE9B;;;;;OAKG;IACH,GAAG,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAC3D;AAED;;GAEG;AACH,qBAAa,eAAe;;IAW1B;;;;;OAKG;IACH,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;IAK1C;;;;;OAKG;IACH,kBAAkB,CAAC,cAAc,EAAE,cAAc,GAAG,IAAI;IAKxD;;;;;OAKG;IACH,gBAAgB,CAAC,YAAY,EAAE,oBAAoB,GAAG,IAAI;IAK1D;;;;;OAKG;IACH,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IAKrC;;;;;OAKG;IACH,YAAY,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IAK9C;;;;;OAKG;IACH,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAK3C;;;;;OAKG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAKpC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAW5B;;;;;OAKG;IACH,UAAU,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI;IAelC;;;;OAIG;IACH,KAAK,IAAI,QAAQ;CAmClB"}