@qlever-llc/trellis 0.7.0-rc.5 → 0.7.0

package/script/js/packages/trellis/npm/src/server/subscription.d.ts

@@ -0,0 +1,99 @@
+import type { JsMsg } from "@nats-io/jetstream";
+import type { InferSchemaType, TrellisAPI } from "@qlever-llc/trellis/contracts";
+/**
+ * Context provided to event handlers with message metadata and acknowledgment controls.
+ */
+export type EventContext = {
+    /** Unique identifier for this event */
+    id: string;
+    /** Timestamp when the event was created */
+    time: Date;
+    /** JetStream sequence number for this message */
+    seq: number;
+    /** Acknowledge successful processing of the message */
+    ack: () => void;
+    /** Negative acknowledge - request redelivery, optionally after a delay in milliseconds */
+    nak: (delay?: number) => void;
+    /** Terminate processing - indicate the message should not be redelivered */
+    term: () => void;
+};
+/**
+ * Options for subscribing to events.
+ */
+export type SubscribeOpts = {
+    /** Filter events by template variables (e.g., { origin: "github", id: "user-123" }) */
+    filter?: Record<string, string>;
+    /** Start consuming from a specific sequence number */
+    startSeq?: number;
+    /** Start consuming from a specific time */
+    startTime?: Date;
+    /** Name for the durable consumer */
+    consumerName?: string;
+};
+export type Events<TA extends TrellisAPI = TrellisAPI> = keyof TA["events"] & string;
+export type Event<TA extends TrellisAPI, E extends Events<TA>> = InferSchemaType<TA["events"][E]["event"]>;
+/**
+ * Handler function for processing events.
+ * @template TA - The API module defining event schemas
+ * @template E - The event key being handled
+ */
+export type EventHandler<TA extends TrellisAPI, E extends Events<TA>> = (event: Event<TA, E>, ctx: EventContext) => Promise<void>;
+/**
+ * Creates an EventContext from a JetStream message.
+ * @param msg - The JetStream message
+ * @param eventId - The unique event identifier
+ * @param eventTime - The event timestamp
+ * @returns An EventContext with message controls
+ */
+export declare function createEventContext(msg: JsMsg, eventId: string, eventTime: Date): EventContext;
+/**
+ * Defines a group of events that should be processed together with ordering guarantees.
+ */
+export type OrderingGroup<TA extends TrellisAPI = TrellisAPI> = {
+    /** Unique name for this ordering group */
+    name: string;
+    /** List of event types that belong to this group */
+    events: Array<Events<TA>>;
+    /** Processing mode: "strict" maintains order, "independent" allows parallel processing */
+    mode: "strict" | "independent";
+};
+/**
+ * A subscription that handles multiple events as a group with shared ordering semantics.
+ */
+export type GroupedSubscription<TA extends TrellisAPI = TrellisAPI> = {
+    /** The ordering group configuration */
+    group: OrderingGroup<TA>;
+    /** Partial map of event types to their handlers */
+    handlers: Partial<Record<Events<TA>, EventHandler<TA, Events<TA>>>>;
+};
+/**
+ * A subscription for a single event type.
+ * @template TA - The API module defining event schemas
+ * @template E - The event type being subscribed to
+ */
+export type SingleSubscription<TA extends TrellisAPI = TrellisAPI, E extends Events<TA> = Events<TA>> = {
+    /** The event type to subscribe to */
+    event: E;
+    /** Handler function for processing events of this type */
+    handler: EventHandler<TA, E>;
+    /** Optional subscription configuration */
+    opts?: SubscribeOpts;
+};
+/**
+ * Union type representing either a grouped or single subscription.
+ */
+export type MultiEventSubscription<TA extends TrellisAPI = TrellisAPI> = GroupedSubscription<TA> | SingleSubscription<TA, Events<TA>>;
+/**
+ * Options for subscribing to multiple events.
+ */
+export type MultiSubscribeOpts = {
+    /** Default processing mode when not specified in a subscription */
+    defaultMode?: "strict" | "independent";
+};
+/**
+ * Type guard to check if a subscription is a GroupedSubscription.
+ * @param sub - The subscription to check
+ * @returns True if the subscription is a GroupedSubscription
+ */
+export declare function isGroupedSubscription<TA extends TrellisAPI>(sub: MultiEventSubscription<TA>): sub is GroupedSubscription<TA>;
+//# sourceMappingURL=subscription.d.ts.map

package/script/js/packages/trellis/npm/src/server/subscription.d.ts.map

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

package/script/js/packages/trellis/npm/src/server/subscription.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEventContext = createEventContext;
+exports.isGroupedSubscription = isGroupedSubscription;
+/**
+ * Creates an EventContext from a JetStream message.
+ * @param msg - The JetStream message
+ * @param eventId - The unique event identifier
+ * @param eventTime - The event timestamp
+ * @returns An EventContext with message controls
+ */
+function createEventContext(msg, eventId, eventTime) {
+    return {
+        id: eventId,
+        time: eventTime,
+        seq: msg.seq,
+        ack: () => msg.ack(),
+        nak: (delay) => msg.nak(delay),
+        term: () => msg.term(),
+    };
+}
+/**
+ * Type guard to check if a subscription is a GroupedSubscription.
+ * @param sub - The subscription to check
+ * @returns True if the subscription is a GroupedSubscription
+ */
+function isGroupedSubscription(sub) {
+    return "group" in sub;
+}

package/script/js/packages/trellis/npm/src/server/transfer.d.ts

@@ -0,0 +1,57 @@
+import { type Result as ResultType } from "@qlever-llc/result";
+import { type NatsConnection } from "@nats-io/nats-core";
+import type { OperationTransferHandle, RuntimeOperationTransferProgress, TrellisAuth } from "../trellis.js";
+import type { StoreError } from "../errors/StoreError.js";
+import { TransferError } from "../errors/TransferError.js";
+import { TypedStore, TypedStoreEntry } from "../store.js";
+import type { DownloadTransferGrant, FileInfo, UploadTransferGrant } from "../transfer.js";
+export type TransferStoreHandle = {
+    open(): Promise<ResultType<TypedStore, StoreError>>;
+};
+export type InitiateUploadArgs = {
+    sessionKey: string;
+    store: string;
+    key: string;
+    expiresInMs: number;
+    maxBytes?: number;
+    contentType?: string;
+    metadata?: Record<string, string>;
+    onProgress?: (progress: RuntimeOperationTransferProgress) => Promise<void> | void;
+    onComplete?: (info: FileInfo) => Promise<void> | void;
+    onError?: (error: TransferError) => Promise<void> | void;
+    onStored?: (stored: StoredTransfer) => Promise<void> | void;
+};
+export type OperationUploadTransfer = {
+    grant: UploadTransferGrant;
+    transfer: OperationTransferHandle;
+};
+export type InitiateDownloadArgs = {
+    sessionKey: string;
+    store: string;
+    key: string;
+    expiresInMs: number;
+};
+type ServiceTransferOpts = {
+    name: string;
+    nc: NatsConnection;
+    auth: TrellisAuth;
+    stores: Record<string, TransferStoreHandle>;
+    chunkBytes?: number;
+};
+export type StoredTransfer = {
+    transferId: string;
+    sessionKey: string;
+    store: TypedStore;
+    entry: TypedStoreEntry;
+    info: FileInfo;
+};
+export declare class ServiceTransfer {
+    #private;
+    constructor(opts: ServiceTransferOpts);
+    initiateUpload(args: InitiateUploadArgs): Promise<ResultType<UploadTransferGrant, TransferError>>;
+    createOperationUpload(args: InitiateUploadArgs): Promise<ResultType<OperationUploadTransfer, TransferError>>;
+    initiateDownload(args: InitiateDownloadArgs): Promise<ResultType<DownloadTransferGrant, TransferError>>;
+    stop(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=transfer.d.ts.map

package/script/js/packages/trellis/npm/src/server/transfer.d.ts.map

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