@qlever-llc/trellis 0.10.22 → 0.11.0-rc.1

package/src/server.ts

@@ -91,7 +91,8 @@ export type TrellisServiceRuntimeFor<TA extends AnyTrellisAPI = TrellisAPI> =
       OperationInputOf<TA, O>,
       OperationProgressOf<TA, O>,
       OperationOutputOf<TA, O>,
-      OperationTransferContextOf<TA, O>
+      OperationTransferContextOf<TA, O>,
+      BaseError
     >;
   };
 
@@ -505,7 +506,10 @@ export class TrellisServiceRuntime extends Trellis<TrellisAPI, TrellisMode> {
     operation: string,
     ctx: RegisteredRuntimeOperationDesc,
     operationId: string,
-  ): AsyncResult<OperationRuntimeHandle<unknown, unknown>, BaseError> {
+  ): AsyncResult<
+    OperationRuntimeHandle<unknown, unknown, BaseError>,
+    BaseError
+  > {
     return AsyncResult.from((async () => {
       const runtime = await this.#resolveOperation(operationId);
       if (!runtime) {
@@ -524,7 +528,7 @@ export class TrellisServiceRuntime extends Trellis<TrellisAPI, TrellisMode> {
   #makeControlledOperation(
     runtime: RuntimeOperationRecord,
     ctx: RegisteredRuntimeOperationDesc,
-  ): OperationRuntimeHandle<unknown, unknown> {
+  ): OperationRuntimeHandle<unknown, unknown, BaseError> {
     return {
       id: runtime.id,
       started: () =>
@@ -586,7 +590,7 @@ export class TrellisServiceRuntime extends Trellis<TrellisAPI, TrellisMode> {
   #makeAcceptedOperation(
     runtime: RuntimeOperationRecord,
     ctx: RegisteredRuntimeOperationDesc,
-  ): AcceptedOperation<unknown, unknown> {
+  ): AcceptedOperation<unknown, unknown, BaseError> {
     return {
       id: runtime.id,
       ref: {
@@ -763,7 +767,9 @@ export class TrellisServiceRuntime extends Trellis<TrellisAPI, TrellisMode> {
     operation: string,
     ctx: RegisteredRuntimeOperationDesc,
     sessionKey: string,
-  ): Promise<Result<AcceptedOperation<unknown, unknown>, UnexpectedError>> {
+  ): Promise<
+    Result<AcceptedOperation<unknown, unknown, BaseError>, UnexpectedError>
+  > {
     const createdAt = new Date().toISOString();
     const operationId = ulid();
     const runtime: RuntimeOperationRecord = {
@@ -1176,7 +1182,7 @@ export class TrellisServiceRuntime extends Trellis<TrellisAPI, TrellisMode> {
 
   override operationHandle(
     operation: string,
-  ): OperationRegistration<unknown, unknown, unknown> {
+  ): OperationRegistration<unknown, unknown, unknown, undefined, BaseError> {
     const ctx = this.api["operations"]
       ?.[operation as keyof typeof this.api.operations] as
         | RegisteredRuntimeOperationDesc
@@ -1215,7 +1221,8 @@ export class TrellisServiceRuntime extends Trellis<TrellisAPI, TrellisMode> {
             unknown,
             unknown,
             unknown,
-            OperationTransferHandle | undefined
+            OperationTransferHandle | undefined,
+            BaseError
           >,
         ) => unknown | Promise<unknown>,
       ) => {

package/src/service/deno.ts

@@ -1,13 +1,8 @@
 import "../_dnt.polyfills.js";
 export {
-  type BoundTrellisService,
-  type FeedHandler,
   type HealthCheckHandler,
   type HealthInfoHandler,
-  type JobArgs,
-  type JobHandler,
   type JobQueue,
-  type JobResult,
   type JobsFacadeOf,
   type OperationHandler,
   type OperationRegistration,

package/src/service/drizzle.ts

@@ -0,0 +1,184 @@
+import "../_dnt.polyfills.js";
+import { type SQL, sql } from "drizzle-orm";
+import type { SqlExecutor, SqlRow } from "./outbox_inbox.js";
+
+/**
+ * Structural Drizzle database or transaction shape accepted by Trellis SQL
+ * outbox helpers.
+ */
+export type DrizzleSqlDatabase = {
+  /** Runs a SQL statement that returns rows. */
+  all(query: SQL): Promise<readonly SqlRow[]>;
+  /** Runs a SQL statement that does not return rows. */
+  run(query: SQL): Promise<unknown>;
+};
+
+/**
+ * Structural transaction runner used by Drizzle-backed Trellis SQL outbox
+ * integrations.
+ */
+export type DrizzleSqlTransactionRunner<
+  TDb extends DrizzleSqlDatabase,
+  TTx extends DrizzleSqlDatabase,
+> = (
+  database: TDb,
+  work: (transaction: TTx) => Promise<unknown>,
+) => Promise<unknown>;
+
+/** Options for Drizzle-backed Trellis SQL outbox integration. */
+export type DrizzleSqlOutboxOptions<
+  TDb extends DrizzleSqlDatabase,
+  TTx extends DrizzleSqlDatabase,
+> = {
+  /** Caller-owned base Drizzle database used for non-transactional outbox work. */
+  readonly db: TDb;
+  /** Caller-owned transaction runner used to scope service work and enqueues. */
+  readonly transaction: DrizzleSqlTransactionRunner<TDb, TTx>;
+};
+
+/**
+ * Adapts a caller-owned Drizzle database or transaction to Trellis'
+ * generic `SqlExecutor` interface.
+ *
+ * This helper is cheap: it creates a small closure object only. It does not open
+ * connections, prepare statements, or inspect schema. Service authors can use it
+ * when adapting Drizzle databases or transactions to the generic
+ * `withSqlOutbox(...)` SQL executor options.
+ */
+export function createDrizzleSqlExecutor(
+  database: DrizzleSqlDatabase,
+): SqlExecutor {
+  return {
+    query(statement, params) {
+      return database.all(bindDrizzleSqlStatement(statement, params));
+    },
+    async execute(statement, params) {
+      await database.run(bindDrizzleSqlStatement(statement, params));
+    },
+  };
+}
+
+/**
+ * Runs work inside a caller-owned Drizzle transaction and provides the
+ * transaction plus a Trellis SQL executor bound to that transaction.
+ */
+export async function runDrizzleSqlTransaction<
+  TDb extends DrizzleSqlDatabase,
+  TTx extends DrizzleSqlDatabase,
+  TResult,
+>(
+  options: DrizzleSqlOutboxOptions<TDb, TTx>,
+  work: (
+    context: { tx: TTx; executor: SqlExecutor },
+  ) => Promise<TResult> | TResult,
+): Promise<TResult> {
+  let result: { value: TResult } | undefined;
+  await options.transaction(options.db, async (tx) => {
+    const value = await work({
+      tx,
+      executor: createDrizzleSqlExecutor(tx),
+    });
+    result = { value };
+    return value;
+  });
+
+  if (result === undefined) {
+    throw new Error("Drizzle SQL transaction runner did not invoke work");
+  }
+
+  return result.value;
+}
+
+/**
+ * Converts a Trellis SQL statement with positional placeholders into a Drizzle
+ * `SQL` object with parameters bound in order.
+ *
+ * Supports SQLite-style `?` placeholders and PostgreSQL-style `$1`, `$2`, ...
+ * placeholders. A single statement must not mix both styles.
+ */
+export function bindDrizzleSqlStatement(
+  statement: string,
+  params: readonly unknown[],
+): SQL {
+  const matches = [...statement.matchAll(/\?|\$(\d+)/g)];
+  const hasQuestionPlaceholders = matches.some((match) => match[0] === "?");
+  const hasNumberedPlaceholders = matches.some((match) =>
+    match[1] !== undefined
+  );
+
+  if (hasQuestionPlaceholders && hasNumberedPlaceholders) {
+    throw new Error(
+      "SQL statement cannot mix ? and $n placeholders for Drizzle binding",
+    );
+  }
+
+  if (hasQuestionPlaceholders) {
+    validateQuestionPlaceholders(matches.length, params.length);
+  } else if (hasNumberedPlaceholders) {
+    validateNumberedPlaceholders(matches, params.length);
+  } else if (params.length !== 0) {
+    throw new Error(
+      `SQL statement has no placeholders but received ${params.length} parameters`,
+    );
+  }
+
+  const chunks: SQL[] = [];
+  let cursor = 0;
+  let nextQuestionParam = 0;
+  for (const match of matches) {
+    const matchIndex = match.index;
+    chunks.push(sql.raw(statement.slice(cursor, matchIndex)));
+    if (match[0] === "?") {
+      chunks.push(sql`${params[nextQuestionParam]}`);
+      nextQuestionParam += 1;
+    } else {
+      const index = Number(match[1]) - 1;
+      chunks.push(sql`${params[index]}`);
+    }
+    cursor = matchIndex + match[0].length;
+  }
+  chunks.push(sql.raw(statement.slice(cursor)));
+
+  return sql.join(chunks);
+}
+
+function validateQuestionPlaceholders(
+  placeholders: number,
+  paramCount: number,
+): void {
+  if (placeholders !== paramCount) {
+    throw new Error(
+      `SQL statement expected ${placeholders} parameters for ? placeholders, received ${paramCount}`,
+    );
+  }
+}
+
+function validateNumberedPlaceholders(
+  matches: RegExpMatchArray[],
+  paramCount: number,
+): void {
+  const referenced = new Set<number>();
+  for (const match of matches) {
+    if (match[1] === undefined) continue;
+    const index = Number(match[1]);
+    if (index < 1) {
+      throw new Error("PostgreSQL SQL placeholder indexes must start at $1");
+    }
+    referenced.add(index);
+  }
+
+  const maxIndex = Math.max(...referenced);
+  if (maxIndex !== paramCount) {
+    throw new Error(
+      `SQL statement expected ${maxIndex} parameters for $n placeholders, received ${paramCount}`,
+    );
+  }
+
+  for (let index = 1; index <= maxIndex; index += 1) {
+    if (!referenced.has(index)) {
+      throw new Error(
+        `SQL statement is missing PostgreSQL placeholder $${index}`,
+      );
+    }
+  }
+}

package/src/service/mod.ts

@@ -28,7 +28,6 @@ export {
 export { mountStandardHealthRpc } from "../server/health_rpc.js";
 export {
   HealthCheckResultSchema,
-  HealthHeartbeatHeaderSchema,
   HealthHeartbeatSchema,
   HealthHeartbeatServiceSchema,
   HealthInfoSchema,
@@ -36,25 +35,29 @@ export {
   HealthRpcSchema,
 } from "../server/health_schemas.js";
 export {
-  type BoundTrellisService,
-  type FeedHandler,
   type HealthCheckHandler,
   type HealthInfoHandler,
-  type JobArgs,
-  type JobHandler,
   type JobQueue,
-  type JobResult,
   type JobsFacadeOf,
   type OperationHandler,
   type OperationRegistration,
   type RpcHandler,
   type ServiceContract,
   type ServiceEventHandler,
+  type SqlOutbox,
+  type SqlOutboxEventEnqueueFacade,
+  type SqlOutboxJobEnqueueFacade,
+  type SqlOutboxJobSubmission,
+  type SqlOutboxTransactionContext,
+  type SqlOutboxTransactionRunner,
   StoreHandle,
   type Trellis,
   TrellisService,
   type TrellisServiceConnectOpts,
   type TrellisServiceConnectTelemetryOpts,
+  type TrellisServiceSqlOutboxCommonOptions,
+  type TrellisServiceSqlOutboxExecutorOptions,
+  type TrellisServiceSqlOutboxOptions,
 } from "../server/service.js";
 export {
   createPostgresOutboxSchema,
@@ -62,6 +65,7 @@ export {
   createSqlOutboxAdapter,
   defaultSqlOutboxTables,
   dispatchOutbox,
+  getSqlOutboxMigrations,
   type InboxRepository,
   type KvOutboxRecord,
   KvOutboxRecordSchema,
@@ -72,16 +76,22 @@ export {
   OutboxDispatcher,
   type OutboxDispatcherOptions,
   type OutboxDispatchResult,
+  type OutboxDispatchRuntime,
   type OutboxKvEntry,
   type OutboxKvStore,
   type OutboxMessage,
   type OutboxMessageState,
-  outboxMessageToPrepared,
+  outboxMessageToPreparedEvent,
+  type OutboxRecordKind,
   type OutboxRepository,
+  type PreparedOutboxRecord,
+  preparedTrellisEventToOutboxRecord,
   type SqlDialect,
   type SqlExecutor,
   SqlInboxRepository,
   type SqlOutboxAdapter,
+  type SqlOutboxMigration,
+  type SqlOutboxMigrationOptions,
   SqlOutboxRepository,
   type SqlOutboxTables,
   type SqlRow,

package/src/service/node.ts

@@ -1,13 +1,8 @@
 import "../_dnt.polyfills.js";
 export {
-  type BoundTrellisService,
-  type FeedHandler,
   type HealthCheckHandler,
   type HealthInfoHandler,
-  type JobArgs,
-  type JobHandler,
   type JobQueue,
-  type JobResult,
   type JobsFacadeOf,
   type OperationHandler,
   type OperationRegistration,