@dbos-inc/node-pg-datasource 5.3.4-preview → 5.3.5-preview

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dbos-inc/node-pg-datasource",
-  "version": "5.3.4-preview",
+  "version": "5.3.5-preview",
   "description": "DBOS DataSource library for Node-Postgres database client",
   "license": "MIT",
   "main": "dist/index.js",

package/index.ts

@@ -1,366 +0,0 @@
-// using https://github.com/brianc/node-postgres
-
-import { DBOS, FunctionName } from '@dbos-inc/dbos-sdk';
-import {
-  type DataSourceTransactionHandler,
-  isPGRetriableTransactionError,
-  DBOSError,
-  DBOSStepAlreadyRecordedError,
-  DBOSWorkflowConflictError,
-  assertStillOwnsWorkflow,
-  replayRecordedStep,
-  registerTransaction,
-  runTransaction,
-  PGTransactionConfig,
-  DBOSDataSource,
-  registerDataSource,
-  DataSourceMigrationOptions,
-  DataSourceSQLExecutor,
-  initializeDataSourceSchemaPG,
-  migrateDataSourcePG,
-  verifyDataSourcePG,
-} from '@dbos-inc/dbos-sdk/datasource';
-import { Client, type ClientBase, type ClientConfig, Pool, type PoolConfig } from 'pg';
-import { AsyncLocalStorage } from 'node:async_hooks';
-import { SuperJSON } from 'superjson';
-
-interface NodePostgresDataSourceContext {
-  client: ClientBase;
-  owner: NodePostgresTransactionHandler;
-}
-
-interface NodePostgresTransactionOptions extends PGTransactionConfig {
-  name?: string;
-}
-
-export { NodePostgresTransactionOptions };
-
-const asyncLocalCtx = new AsyncLocalStorage<NodePostgresDataSourceContext>();
-
-function clientExecutor(client: ClientBase): DataSourceSQLExecutor {
-  return async (sql) => (await client.query<Record<string, unknown>>(sql)).rows;
-}
-
-class NodePostgresTransactionHandler implements DataSourceTransactionHandler {
-  #poolField: Pool | undefined;
-  readonly schemaName: string;
-
-  constructor(
-    readonly name: string,
-    private readonly config: PoolConfig,
-    schemaName: string = 'dbos',
-    private readonly options: DataSourceMigrationOptions = {},
-  ) {
-    this.schemaName = schemaName;
-  }
-
-  async initialize(): Promise<void> {
-    const pool = this.#poolField;
-    this.#poolField = new Pool(this.config);
-    await pool?.end();
-
-    if (this.options.runMigrations === false) {
-      const client = await this.#poolField.connect();
-      try {
-        await verifyDataSourcePG(clientExecutor(client), this.schemaName, this.name);
-      } finally {
-        client.release();
-      }
-      return;
-    }
-
-    try {
-      await this.#transaction((client) => migrateDataSourcePG(clientExecutor(client), this.schemaName));
-    } catch (err) {
-      throw new Error(
-        `In initialization of 'NodePostgresDataSource' ${this.name}: The '${this.schemaName}' transaction schema could not be migrated: ${(err as Error).message}. This should be added to your database migrations.
-        See: https://docs.dbos.dev/typescript/tutorials/transaction-tutorial#installing-the-dbos-schema`,
-      );
-    }
-  }
-
-  async destroy(): Promise<void> {
-    const pool = this.#poolField;
-    this.#poolField = undefined;
-    await pool?.end();
-  }
-
-  get #pool(): Pool {
-    if (!this.#poolField) {
-      throw new Error(`DataSource ${this.name} is not initialized.`);
-    }
-    return this.#poolField;
-  }
-
-  async deleteCheckpoints(workflowID: string, startStep: number, beforeCommit?: () => Promise<void>): Promise<void> {
-    await this.#transaction(async (client) => {
-      await client.query(
-        /*sql*/
-        `DELETE FROM "${this.schemaName}".transaction_completion
-         WHERE workflow_id = $1 AND function_num >= $2`,
-        [workflowID, startStep],
-      );
-      await beforeCommit?.();
-    });
-  }
-
-  async #checkExecution(
-    workflowID: string,
-    stepID: number,
-  ): Promise<{ output: string | null } | { error: string } | undefined> {
-    type Result = { output: string | null; error: string | null };
-    const { rows } = await this.#pool.query<Result>(
-      /*sql*/
-      `SELECT output, error FROM "${this.schemaName}".transaction_completion
-       WHERE workflow_id = $1 AND function_num = $2`,
-      [workflowID, stepID],
-    );
-    if (rows.length === 0) {
-      return undefined;
-    }
-    const { output, error } = rows[0];
-    return error !== null ? { error } : { output };
-  }
-
-  static async #recordOutput(
-    client: ClientBase,
-    workflowID: string,
-    stepID: number,
-    output: string | null,
-    schemaName: string,
-  ): Promise<void> {
-    const { rows } = await client.query(
-      /*sql*/
-      `INSERT INTO "${schemaName}".transaction_completion (workflow_id, function_num, output)
-       VALUES ($1, $2, $3)
-       ON CONFLICT (workflow_id, function_num) DO NOTHING
-       RETURNING workflow_id`,
-      [workflowID, stepID, output],
-    );
-    if (rows.length === 0) {
-      throw new DBOSStepAlreadyRecordedError(workflowID, stepID);
-    }
-    // Holding this step's row, so a later owner's insert waits on our commit.
-    await assertStillOwnsWorkflow(workflowID);
-  }
-
-  async #recordError(workflowID: string, stepID: number, error: string): Promise<void> {
-    const { rows } = await this.#pool.query(
-      /*sql*/
-      `INSERT INTO "${this.schemaName}".transaction_completion (workflow_id, function_num, error)
-       VALUES ($1, $2, $3)
-       ON CONFLICT (workflow_id, function_num) DO NOTHING
-       RETURNING workflow_id`,
-      [workflowID, stepID, error],
-    );
-    if (rows.length === 0) {
-      throw new DBOSStepAlreadyRecordedError(workflowID, stepID);
-    }
-  }
-
-  // A duplicate execution won the race, so its recorded outcome is the durable one.
-  async #replayConflictingStep<Return>(workflowID: string, stepID: number): Promise<Return> {
-    const recorded = await this.#checkExecution(workflowID, stepID);
-    if (recorded === undefined) {
-      throw new DBOSError(
-        `Step ${stepID} of workflow ${workflowID} conflicted with a concurrent execution, but no recorded outcome was found`,
-      );
-    }
-    return replayRecordedStep<Return>(recorded);
-  }
-
-  async #transaction<Return>(
-    func: (client: ClientBase) => Promise<Return>,
-    config: NodePostgresTransactionOptions = {},
-  ): Promise<Return> {
-    const isolationLevel = config?.isolationLevel ? `ISOLATION LEVEL ${config.isolationLevel}` : '';
-    const readOnly = config?.readOnly ?? false;
-    const accessMode = config?.readOnly === undefined ? '' : readOnly ? 'READ ONLY' : 'READ WRITE';
-
-    const client = await this.#pool.connect();
-    try {
-      await client.query(/*sql*/ `BEGIN ${isolationLevel} ${accessMode}`);
-      const result = await func(client);
-      await client.query(/*sql*/ `COMMIT`);
-      return result;
-    } catch (error) {
-      await client.query(/*sql*/ `ROLLBACK`);
-      throw error;
-    } finally {
-      client.release();
-    }
-  }
-
-  async invokeTransactionFunction<This, Args extends unknown[], Return>(
-    config: NodePostgresTransactionOptions | undefined,
-    target: This,
-    func: (this: This, ...args: Args) => Promise<Return>,
-    ...args: Args
-  ): Promise<Return> {
-    const workflowID = DBOS.workflowID;
-    const stepID = DBOS.stepID;
-    if (workflowID !== undefined && stepID === undefined) {
-      throw new Error('DBOS.stepID is undefined inside a workflow.');
-    }
-
-    const readOnly = config?.readOnly ?? false;
-    const saveResults = !readOnly && workflowID !== undefined;
-
-    // Retry loop if appropriate
-    let retryWaitMS = 1;
-    const backoffFactor = 1.5;
-    const maxRetryWaitMS = 2000; // Maximum wait 2 seconds.
-
-    while (true) {
-      // Check to see if this tx has already been executed
-      const previousResult = saveResults ? await this.#checkExecution(workflowID, stepID!) : undefined;
-      if (previousResult) {
-        return replayRecordedStep<Return>(previousResult);
-      }
-
-      try {
-        const result = await this.#transaction<Return>(async (client) => {
-          // execute user's transaction function
-          const result = await asyncLocalCtx.run({ client, owner: this }, async () => {
-            return (await func.call(target, ...args)) as Return;
-          });
-
-          // save the output of read/write transactions
-          if (saveResults) {
-            await NodePostgresTransactionHandler.#recordOutput(
-              client,
-              workflowID,
-              stepID!,
-              SuperJSON.stringify(result),
-              this.schemaName,
-            );
-          }
-
-          return result;
-        }, config);
-
-        return result;
-      } catch (error) {
-        if (saveResults && error instanceof DBOSStepAlreadyRecordedError) {
-          return await this.#replayConflictingStep<Return>(workflowID, stepID!);
-        }
-        // The new owner wins; recording an error here would replay it as this step's outcome.
-        if (error instanceof DBOSWorkflowConflictError) throw error;
-        if (isPGRetriableTransactionError(error)) {
-          DBOS.span?.addEvent('TXN SERIALIZATION FAILURE', { retryWaitMillis: retryWaitMS }, performance.now());
-          await new Promise((resolve) => setTimeout(resolve, retryWaitMS));
-          retryWaitMS = Math.min(retryWaitMS * backoffFactor, maxRetryWaitMS);
-          continue;
-        } else {
-          if (saveResults) {
-            const message = SuperJSON.stringify(error);
-            try {
-              await this.#recordError(workflowID, stepID!, message);
-            } catch (recordError) {
-              if (recordError instanceof DBOSStepAlreadyRecordedError) {
-                return await this.#replayConflictingStep<Return>(workflowID, stepID!);
-              }
-              throw recordError;
-            }
-          }
-
-          throw error;
-        }
-      }
-    }
-  }
-}
-
-export class NodePostgresDataSource implements DBOSDataSource<NodePostgresTransactionOptions> {
-  static #getClient(p?: NodePostgresTransactionHandler): ClientBase {
-    if (!DBOS.isInTransaction()) {
-      throw new Error('Invalid use of NodePostgresDataSource.client outside of a DBOS transaction.');
-    }
-    const ctx = asyncLocalCtx.getStore();
-    if (!ctx) {
-      throw new Error('Invalid use of NodePostgresDataSource.client outside of a DBOS transaction.');
-    }
-    if (p && p !== ctx.owner) {
-      throw new Error('Use of `NodePostgresDataSource.client` from the wrong object');
-    }
-    return ctx.client;
-  }
-
-  static get client() {
-    return NodePostgresDataSource.#getClient(undefined);
-  }
-
-  get client() {
-    return NodePostgresDataSource.#getClient(this.#provider);
-  }
-
-  /**
-   * Create or migrate the DBOS transaction schema, typically with a privileged role,
-   * optionally granting `applicationRole` the minimal permissions to use it.
-   */
-  static async initializeDBOSSchema(
-    config: ClientConfig,
-    schemaName: string = 'dbos',
-    options: { applicationRole?: string } = {},
-  ): Promise<void> {
-    const client = new Client(config);
-    try {
-      await client.connect();
-      await client.query('BEGIN');
-      try {
-        await initializeDataSourceSchemaPG(clientExecutor(client), schemaName, options.applicationRole);
-        await client.query('COMMIT');
-      } catch (err) {
-        await client.query('ROLLBACK');
-        throw err;
-      }
-    } finally {
-      await client.end();
-    }
-  }
-
-  #provider: NodePostgresTransactionHandler;
-
-  constructor(
-    readonly name: string,
-    config: PoolConfig,
-    schemaName: string = 'dbos',
-    options: DataSourceMigrationOptions = {},
-  ) {
-    this.#provider = new NodePostgresTransactionHandler(name, config, schemaName, options);
-    registerDataSource(this.#provider);
-  }
-
-  async runTransaction<T>(func: () => Promise<T>, config?: NodePostgresTransactionOptions) {
-    return await runTransaction(func, config?.name ?? func.name, { dsName: this.name, config });
-  }
-
-  registerTransaction<This, Args extends unknown[], Return>(
-    func: (this: This, ...args: Args) => Promise<Return>,
-    config?: NodePostgresTransactionOptions & FunctionName,
-  ): (this: This, ...args: Args) => Promise<Return> {
-    return registerTransaction(this.name, func, config);
-  }
-
-  transaction(config?: NodePostgresTransactionOptions) {
-    // eslint-disable-next-line @typescript-eslint/no-this-alias
-    const ds = this;
-    return function decorator<This, Args extends unknown[], Return>(
-      target: object,
-      propertyKey: PropertyKey,
-      descriptor: TypedPropertyDescriptor<(this: This, ...args: Args) => Promise<Return>>,
-    ) {
-      if (!descriptor.value) {
-        throw Error('Use of decorator when original method is undefined');
-      }
-
-      descriptor.value = ds.registerTransaction(descriptor.value, {
-        ...config,
-        name: config?.name ?? String(propertyKey),
-        ctorOrProto: target,
-      });
-
-      return descriptor;
-    };
-  }
-}

package/jest.config.js

@@ -1,8 +0,0 @@
-/** @type {import('ts-jest').JestConfigWithTsJest} */
-module.exports = {
-  preset: 'ts-jest',
-  testEnvironment: 'node',
-  testRegex: '((\\.|/)(test|spec))\\.ts?$',
-  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
-  modulePaths: ['./'],
-};

package/tests/config.test.ts

@@ -1,31 +0,0 @@
-import { Client } from 'pg';
-import { NodePostgresDataSource } from '../index';
-import { dropDB, ensureDB } from './test-helpers';
-
-describe('NodePostgresDataSource.configure', () => {
-  const config = { user: 'postgres', database: 'nodepg_ds_config_test' };
-
-  beforeAll(async () => {
-    const client = new Client({ ...config, database: 'postgres' });
-    try {
-      await client.connect();
-      await dropDB(client, config.database, true);
-      await ensureDB(client, config.database);
-    } finally {
-      await client.end();
-    }
-  });
-
-  test('configure creates tx outputs table', async () => {
-    await NodePostgresDataSource.initializeDBOSSchema(config);
-
-    const client = new Client(config);
-    try {
-      await client.connect();
-      const result = await client.query('SELECT workflow_id, function_num, output FROM dbos.transaction_completion');
-      expect(result.rows.length).toBe(0);
-    } finally {
-      await client.end();
-    }
-  });
-});

package/tests/datasource.test.ts

@@ -1,813 +0,0 @@
-import { DBOS, DBOSWorkflowConflictError } from '@dbos-inc/dbos-sdk';
-import { Client, Pool } from 'pg';
-import { NodePostgresDataSource } from '..';
-import { dropDB, ensureDB } from './test-helpers';
-import { randomUUID } from 'crypto';
-import { SuperJSON } from 'superjson';
-
-const config = { user: 'postgres', database: 'node_pg_ds_test_datasource' };
-const dataSource = new NodePostgresDataSource('app-db', config);
-
-interface transaction_completion {
-  workflow_id: string;
-  function_num: number;
-  output: string | null;
-  error: string | null;
-}
-
-describe('NodePostgresDataSource', () => {
-  const userDB = new Pool(config);
-
-  beforeAll(async () => {
-    await createDatabases(userDB, true);
-  });
-
-  afterAll(async () => {
-    await userDB.end();
-  });
-
-  beforeEach(async () => {
-    DBOS.setConfig({ name: 'node-pg-ds-test' });
-    await DBOS.launch();
-  });
-
-  afterEach(async () => {
-    await DBOS.shutdown();
-  });
-
-  test('insert dataSource.register function', async () => {
-    const user = 'helloTest1';
-
-    await userDB.query('DELETE FROM greetings WHERE name = $1', [user]);
-    const workflowID = randomUUID();
-
-    await expect(DBOS.withNextWorkflowID(workflowID, () => regInsertWorkflowReg(user))).resolves.toMatchObject({
-      user,
-      greet_count: 1,
-    });
-
-    const { rows } = await userDB.query<transaction_completion>(
-      'SELECT * FROM dbos.transaction_completion WHERE workflow_id = $1',
-      [workflowID],
-    );
-    // Completion cleared the checkpoint the transaction wrote.
-    expect(rows).toHaveLength(0);
-  });
-
-  test('rewind drops the checkpoints past the cut', async () => {
-    const user = 'rewindTest';
-    await userDB.query('DELETE FROM greetings WHERE name = $1', [user]);
-    rewindState = newRewindState();
-    const workflowID = randomUUID();
-
-    // A cancelled workflow keeps its checkpoints, so the rewind has some to cut.
-    const execution = DBOS.withNextWorkflowID(workflowID, () => regGatedTwoInsertWorkflow(user));
-    await Promise.race([rewindState.atGate.opened, execution]);
-    await DBOS.cancelWorkflow(workflowID);
-    rewindState.release.open();
-    await expect(execution).rejects.toThrow(/has been cancelled/);
-    expect((await completions(workflowID)).map((r) => r.function_num)).toEqual([0, 1]);
-
-    // Hold the queue's only worker so the rewound workflow waits while its checkpoints are inspected.
-    await DBOS.registerQueue('nodepg_rewind_gate', { workerConcurrency: 1, onConflict: 'always_update' });
-    const blocker = await DBOS.startWorkflow(regQueueBlocker, { queueName: 'nodepg_rewind_gate' })();
-    await rewindState.blockerStarted.opened;
-    const handle = await DBOS.rewindWorkflow<number[]>(workflowID, {
-      startStep: 1,
-      queueName: 'nodepg_rewind_gate',
-    });
-    expect((await completions(workflowID)).map((r) => r.function_num)).toEqual([0]);
-
-    // The first transaction replays and still reports 1; the second really runs again, taking the table to 3.
-    rewindState.unblock.open();
-    await blocker.getResult();
-    await expect(handle.getResult()).resolves.toEqual([1, 3]);
-    expect(await completions(workflowID)).toHaveLength(0);
-  });
-
-  async function completions(workflowID: string) {
-    const { rows } = await userDB.query<transaction_completion>(
-      'SELECT * FROM dbos.transaction_completion WHERE workflow_id = $1 ORDER BY function_num',
-      [workflowID],
-    );
-    return rows;
-  }
-
-  test('rerun insert dataSource.register function', async () => {
-    const user = 'rerunTest1';
-
-    await userDB.query('DELETE FROM greetings WHERE name = $1', [user]);
-    const workflowID = randomUUID();
-
-    const result = await DBOS.withNextWorkflowID(workflowID, () => regInsertWorkflowReg(user));
-    expect(result).toMatchObject({ user, greet_count: 1 });
-
-    await expect(DBOS.withNextWorkflowID(workflowID, () => regInsertWorkflowReg(user))).resolves.toMatchObject(result);
-  });
-
-  test('insert dataSource.runAsTx function', async () => {
-    const user = 'helloTest2';
-
-    await userDB.query('DELETE FROM greetings WHERE name = $1', [user]);
-    const workflowID = randomUUID();
-
-    await expect(DBOS.withNextWorkflowID(workflowID, () => regInsertWorkflowRunTx(user))).resolves.toMatchObject({
-      user,
-      greet_count: 1,
-    });
-
-    const { rows } = await userDB.query<transaction_completion>(
-      'SELECT * FROM dbos.transaction_completion WHERE workflow_id = $1',
-      [workflowID],
-    );
-    // Completion cleared the checkpoint the transaction wrote.
-    expect(rows).toHaveLength(0);
-  });
-
-  test('rerun insert dataSource.runAsTx function', async () => {
-    const user = 'rerunTest2';
-
-    await userDB.query('DELETE FROM greetings WHERE name = $1', [user]);
-    const workflowID = randomUUID();
-
-    const result = await DBOS.withNextWorkflowID(workflowID, () => regInsertWorkflowRunTx(user));
-    expect(result).toMatchObject({ user, greet_count: 1 });
-
-    await expect(DBOS.withNextWorkflowID(workflowID, () => regInsertWorkflowRunTx(user))).resolves.toMatchObject(
-      result,
-    );
-  });
-
-  async function throws<R>(func: () => Promise<R>): Promise<unknown> {
-    try {
-      await func();
-      fail('Expected function to throw an error');
-    } catch (error) {
-      return error;
-    }
-  }
-
-  test('error dataSource.register function', async () => {
-    const user = 'errorTest1';
-
-    await userDB.query('DELETE FROM greetings WHERE name = $1', [user]);
-    await userDB.query('INSERT INTO greetings("name","greet_count") VALUES($1,10);', [user]);
-    const workflowID = randomUUID();
-
-    const error = await throws(() => DBOS.withNextWorkflowID(workflowID, () => regErrorWorkflowReg(user)));
-    expect(error).toBeInstanceOf(Error);
-    expect((error as Error).message).toMatch(/^test error \d+$/);
-
-    const { rows } = await userDB.query<greetings>('SELECT * FROM greetings WHERE name = $1', [user]);
-    expect(rows.length).toBe(1);
-    expect(rows[0].greet_count).toBe(10);
-
-    const { rows: txOutput } = await userDB.query<transaction_completion>(
-      'SELECT * FROM dbos.transaction_completion WHERE workflow_id = $1',
-      [workflowID],
-    );
-    // Completion cleared the checkpoint the transaction wrote.
-    expect(txOutput).toHaveLength(0);
-  });
-
-  test('rerun error dataSource.register function', async () => {
-    const user = 'rerunErrorTest1';
-
-    await userDB.query('DELETE FROM greetings WHERE name = $1', [user]);
-    await userDB.query('INSERT INTO greetings("name","greet_count") VALUES($1,10);', [user]);
-    const workflowID = randomUUID();
-
-    const error = await throws(() => DBOS.withNextWorkflowID(workflowID, () => regErrorWorkflowReg(user)));
-    expect(error).toBeInstanceOf(Error);
-    expect((error as Error).message).toMatch(/^test error \d+$/);
-
-    const error2 = await throws(() => DBOS.withNextWorkflowID(workflowID, () => regErrorWorkflowReg(user)));
-    expect(error2).toBeInstanceOf(Error);
-    expect((error2 as Error).message).toMatch((error as Error).message);
-  });
-
-  test('error dataSource.runAsTx function', async () => {
-    const user = 'errorTest2';
-
-    await userDB.query('DELETE FROM greetings WHERE name = $1', [user]);
-    await userDB.query('INSERT INTO greetings("name","greet_count") VALUES($1,10);', [user]);
-    const workflowID = randomUUID();
-
-    const error = await throws(() => DBOS.withNextWorkflowID(workflowID, () => regErrorWorkflowRunTx(user)));
-    expect(error).toBeInstanceOf(Error);
-    expect((error as Error).message).toMatch(/^test error \d+$/);
-
-    const { rows } = await userDB.query<greetings>('SELECT * FROM greetings WHERE name = $1', [user]);
-    expect(rows.length).toBe(1);
-    expect(rows[0].greet_count).toBe(10);
-
-    const { rows: txOutput } = await userDB.query<transaction_completion>(
-      'SELECT * FROM dbos.transaction_completion WHERE workflow_id = $1',
-      [workflowID],
-    );
-    // Completion cleared the checkpoint the transaction wrote.
-    expect(txOutput).toHaveLength(0);
-  });
-
-  test('rerun error dataSource.runAsTx function', async () => {
-    const user = 'rerunErrorTest2';
-
-    await userDB.query('DELETE FROM greetings WHERE name = $1', [user]);
-    await userDB.query('INSERT INTO greetings("name","greet_count") VALUES($1,10);', [user]);
-    const workflowID = randomUUID();
-
-    const error = await throws(() => DBOS.withNextWorkflowID(workflowID, () => regErrorWorkflowRunTx(user)));
-    expect(error).toBeInstanceOf(Error);
-    expect((error as Error).message).toMatch(/^test error \d+$/);
-
-    const error2 = await throws(() => DBOS.withNextWorkflowID(workflowID, () => regErrorWorkflowRunTx(user)));
-    expect(error2).toBeInstanceOf(Error);
-    expect((error2 as Error).message).toMatch((error as Error).message);
-  });
-
-  test('readonly dataSource.register function', async () => {
-    const user = 'readTest1';
-
-    await userDB.query('DELETE FROM greetings WHERE name = $1', [user]);
-    await userDB.query('INSERT INTO greetings("name","greet_count") VALUES($1,10);', [user]);
-
-    const workflowID = randomUUID();
-    await expect(DBOS.withNextWorkflowID(workflowID, () => regReadWorkflowReg(user))).resolves.toMatchObject({
-      user,
-      greet_count: 10,
-    });
-
-    const { rows } = await userDB.query('SELECT * FROM dbos.transaction_completion WHERE workflow_id = $1', [
-      workflowID,
-    ]);
-    expect(rows.length).toBe(0);
-  });
-
-  test('readonly dataSource.runAsTx function', async () => {
-    const user = 'readTest2';
-
-    await userDB.query('DELETE FROM greetings WHERE name = $1', [user]);
-    await userDB.query('INSERT INTO greetings("name","greet_count") VALUES($1,10);', [user]);
-
-    const workflowID = randomUUID();
-    await expect(DBOS.withNextWorkflowID(workflowID, () => regReadWorkflowRunTx(user))).resolves.toMatchObject({
-      user,
-      greet_count: 10,
-    });
-
-    const { rows } = await userDB.query('SELECT * FROM dbos.transaction_completion WHERE workflow_id = $1', [
-      workflowID,
-    ]);
-    expect(rows.length).toBe(0);
-  });
-
-  test('static dataSource.register methods', async () => {
-    const user = 'staticTest1';
-
-    await userDB.query('DELETE FROM greetings WHERE name = $1', [user]);
-
-    const workflowID = randomUUID();
-    await expect(DBOS.withNextWorkflowID(workflowID, () => regStaticWorkflow(user))).resolves.toMatchObject([
-      { user, greet_count: 1 },
-      { user, greet_count: 1 },
-    ]);
-  });
-
-  test('instance dataSource.register methods', async () => {
-    const user = 'instanceTest1';
-
-    await userDB.query('DELETE FROM greetings WHERE name = $1', [user]);
-
-    const workflowID = randomUUID();
-    await expect(DBOS.withNextWorkflowID(workflowID, () => regInstanceWorkflow(user))).resolves.toMatchObject([
-      { user, greet_count: 1 },
-      { user, greet_count: 1 },
-    ]);
-  });
-
-  test('invoke-reg-tx-fun-outside-wf', async () => {
-    const user = 'outsideWfUser' + Date.now();
-    const result = await regInsertFunction(user);
-    expect(result).toMatchObject({ user, greet_count: 1 });
-
-    const txResults = await userDB.query('SELECT * FROM dbos.transaction_completion WHERE output LIKE $1', [
-      `%${user}%`,
-    ]);
-    expect(txResults.rows.length).toBe(0);
-  });
-
-  test('invoke-reg-tx-static-method-outside-wf', async () => {
-    const user = 'outsideWfUser' + Date.now();
-    const result = await StaticClass.insertFunction(user);
-    expect(result).toMatchObject({ user, greet_count: 1 });
-
-    const txResults = await userDB.query('SELECT * FROM dbos.transaction_completion WHERE output LIKE $1', [
-      `%${user}%`,
-    ]);
-    expect(txResults.rows.length).toBe(0);
-  });
-
-  test('invoke-reg-tx-inst-method-outside-wf', async () => {
-    const user = 'outsideWfUser' + Date.now();
-    const instance = new InstanceClass();
-    const result = await instance.insertFunction(user);
-    expect(result).toMatchObject({ user, greet_count: 1 });
-
-    const txResults = await userDB.query('SELECT * FROM dbos.transaction_completion WHERE output LIKE $1', [
-      `%${user}%`,
-    ]);
-    expect(txResults.rows.length).toBe(0);
-  });
-
-  test('duplicate execution replays the winner result', async () => {
-    await userDB.query('DELETE FROM race_side_effects');
-    raceState.callCount = 0;
-
-    // A loser whose body succeeds: the collision happens on the result-recording insert.
-    raceState.plantWinner = true;
-    raceState.plantWinnerError = false;
-    raceState.fail = false;
-    const wfid1 = randomUUID();
-    await expect(DBOS.withNextWorkflowID(wfid1, () => regRaceWorkflow())).resolves.toBe('winner-result');
-    expect(raceState.callCount).toBe(1); // the loser did run its body
-
-    // A loser whose body fails: the collision moves to the error-recording insert,
-    // and the winner's result still wins over the loser's own error.
-    raceState.plantWinner = true;
-    raceState.plantWinnerError = false;
-    raceState.fail = true;
-    const wfid2 = randomUUID();
-    await expect(DBOS.withNextWorkflowID(wfid2, () => regRaceWorkflow())).resolves.toBe('winner-result');
-    expect(raceState.callCount).toBe(2);
-
-    // A winner that recorded an error: the loser replays that throw instead of its own result.
-    raceState.plantWinner = true;
-    raceState.plantWinnerError = true;
-    raceState.fail = false;
-    const wfid3 = randomUUID();
-    const winnerError = await throws(() => DBOS.withNextWorkflowID(wfid3, () => regRaceWorkflow()));
-    expect((winnerError as Error).message).toBe('winner-error');
-    expect(raceState.callCount).toBe(3);
-
-    // Every loser's writes were discarded, and completion cleared the winners' checkpoints.
-    const { rows: tags } = await userDB.query<{ tag: string }>('SELECT tag FROM race_side_effects');
-    expect(tags).toHaveLength(0);
-    const { rows: txOutput } = await userDB.query<transaction_completion>(
-      'SELECT * FROM dbos.transaction_completion WHERE workflow_id = ANY($1)',
-      [[wfid1, wfid2, wfid3]],
-    );
-    expect(txOutput).toHaveLength(0);
-  });
-
-  /** Completion clears the checkpoints, so the workflow reads them back while it still runs. */
-  test('transactions record their outcomes as checkpoints', async () => {
-    const user = 'checkpointProbe';
-    await userDB.query('DELETE FROM greetings WHERE name = $1', [user]);
-    const workflowID = randomUUID();
-    const message = await DBOS.withNextWorkflowID(workflowID, () => regCheckpointProbeWorkflow(user));
-    expect(message).toMatch(/^test error \d+$/);
-
-    expect(probeState.rows).toHaveLength(2);
-    const [output, error] = probeState.rows;
-    expect(output).toMatchObject({ workflow_id: workflowID, function_num: 0, error: null });
-    expect(SuperJSON.parse(output.output!)).toMatchObject({ user, greet_count: 1 });
-    expect(error).toMatchObject({ workflow_id: workflowID, function_num: 1, output: null });
-    expect(SuperJSON.parse<Error>(error.error!).message).toBe(message);
-    expect(await readCompletions(workflowID)).toHaveLength(0);
-  });
-
-  /** The checkpoint may be the new owner's only record of the transaction, so a stale execution's cleanup rolls back. */
-  test('a stale execution keeps the checkpoints at completion', async () => {
-    const user = 'handOffTest';
-    await userDB.query('DELETE FROM greetings WHERE name = $1', [user]);
-    const handedOff = new Promise<void>((resolve) => (handOffState.signal = resolve));
-    const workflowID = randomUUID();
-    const execution = DBOS.withNextWorkflowID(workflowID, () => regHandOffWorkflow(user));
-    // Surfaces the workflow's own error if it fails before handing off.
-    await Promise.race([handedOff, execution]);
-
-    // Its outcome is refused too, so the execution parks until the workflow is cancelled.
-    await DBOS.cancelWorkflow(workflowID);
-    await expect(execution).rejects.toThrow(/has been cancelled/);
-    expect(await readCompletions(workflowID)).toHaveLength(1);
-  });
-
-  /** A stale execution cannot apply a step the new owner also runs, nor leave an outcome for it. */
-  test('an execution that loses the workflow mid-transaction rolls back', async () => {
-    await userDB.query('DELETE FROM race_side_effects');
-    const workflowID = randomUUID();
-    await expect(DBOS.withNextWorkflowID(workflowID, () => regStaleWorkflow())).resolves.toBe('conflicted');
-
-    const { rows: tags } = await userDB.query<{ tag: string }>('SELECT tag FROM race_side_effects');
-    expect(tags).toHaveLength(0);
-    expect(staleState.completionsAtConflict).toBe(0);
-    const sysDB = new Client(sysConfig);
-    try {
-      await sysDB.connect();
-      const { rows: steps } = await sysDB.query('SELECT * FROM dbos.operation_outputs WHERE workflow_uuid = $1', [
-        workflowID,
-      ]);
-      expect(steps).toHaveLength(0);
-    } finally {
-      await sysDB.end();
-    }
-  });
-});
-
-export interface greetings {
-  name: string;
-  greet_count: number;
-}
-
-async function createDatabases(userDB: Pool, createTxCompletion: boolean) {
-  {
-    const client = new Client({ ...config, database: 'postgres' });
-    try {
-      await client.connect();
-      await dropDB(client, 'node_pg_ds_test', true);
-      await dropDB(client, 'node_pg_ds_test_dbos_sys', true);
-      await dropDB(client, config.database, true);
-      await ensureDB(client, config.database);
-    } finally {
-      await client.end();
-    }
-  }
-
-  {
-    const client = await userDB.connect();
-    try {
-      await client.query(
-        'CREATE TABLE greetings(name text NOT NULL, greet_count integer DEFAULT 0, PRIMARY KEY(name))',
-      );
-      await client.query('CREATE TABLE race_side_effects(tag text NOT NULL)');
-    } finally {
-      client.release();
-    }
-  }
-
-  if (createTxCompletion) {
-    await NodePostgresDataSource.initializeDBOSSchema(config);
-  }
-}
-
-async function insertFunction(user: string) {
-  const { rows } = await NodePostgresDataSource.client.query<Pick<greetings, 'greet_count'>>(
-    `INSERT INTO greetings(name, greet_count) 
-     VALUES($1, 1) 
-     ON CONFLICT(name)
-     DO UPDATE SET greet_count = greetings.greet_count + 1
-     RETURNING greet_count`,
-    [user],
-  );
-  const row = rows.length > 0 ? rows[0] : undefined;
-  return { user, greet_count: row?.greet_count, now: Date.now() };
-}
-
-async function errorFunction(user: string) {
-  const _result = await insertFunction(user);
-  throw new Error(`test error ${Date.now()}`);
-}
-
-const raceState = { callCount: 0, plantWinner: false, plantWinnerError: false, fail: false };
-
-async function raceFunction() {
-  raceState.callCount += 1;
-  await NodePostgresDataSource.client.query('INSERT INTO race_side_effects(tag) VALUES ($1)', [
-    `run-${raceState.callCount}`,
-  ]);
-  if (raceState.plantWinner) {
-    raceState.plantWinner = false;
-    await plantWinnerCompletion();
-  }
-  if (raceState.fail) {
-    throw new Error("loser's own failure");
-  }
-  return `result-${raceState.callCount}`;
-}
-
-// A duplicate execution commits its result while this transaction is still open, so this
-// execution's pre-check missed it but its completion insert will collide with it.
-async function plantWinnerCompletion() {
-  const winner = new Client(config);
-  try {
-    await winner.connect();
-    const [column, value] = raceState.plantWinnerError
-      ? ['error', SuperJSON.stringify(new Error('winner-error'))]
-      : ['output', SuperJSON.stringify('winner-result')];
-    await winner.query(
-      `INSERT INTO dbos.transaction_completion (workflow_id, function_num, ${column}) VALUES ($1, $2, $3)`,
-      [DBOS.workflowID, DBOS.stepID, value],
-    );
-  } finally {
-    await winner.end();
-  }
-}
-
-async function readFunction(user: string) {
-  const { rows } = await dataSource.client.query<Pick<greetings, 'greet_count'>>(
-    `SELECT greet_count
-     FROM greetings
-     WHERE name = $1`,
-    [user],
-  );
-  const row = rows.length > 0 ? rows[0] : undefined;
-  return { user, greet_count: row?.greet_count, now: Date.now() };
-}
-
-const regRaceFunction = dataSource.registerTransaction(raceFunction);
-
-async function raceWorkflow() {
-  return await regRaceFunction();
-}
-
-const regRaceWorkflow = DBOS.registerWorkflow(raceWorkflow);
-
-const regInsertFunction = dataSource.registerTransaction(insertFunction);
-
-const regErrorFunction = dataSource.registerTransaction(errorFunction);
-
-const sysConfig = { ...config, database: 'node_pg_ds_test_dbos_sys' };
-
-/** Set the workflow's ownership token, returning the one it replaced. */
-async function setOwner(workflowID: string, ownerXid: string | null): Promise<string | null> {
-  const sysDB = new Client(sysConfig);
-  try {
-    await sysDB.connect();
-    const { rows } = await sysDB.query<{ owner_xid: string | null }>(
-      'SELECT owner_xid FROM dbos.workflow_status WHERE workflow_uuid = $1',
-      [workflowID],
-    );
-    await sysDB.query('UPDATE dbos.workflow_status SET owner_xid = $2 WHERE workflow_uuid = $1', [
-      workflowID,
-      ownerXid,
-    ]);
-    return rows[0].owner_xid;
-  } finally {
-    await sysDB.end();
-  }
-}
-
-/** The checkpoints this data source holds for the workflow, read on a connection of their own. */
-async function readCompletions(workflowID: string): Promise<transaction_completion[]> {
-  const client = new Client(config);
-  try {
-    await client.connect();
-    const { rows } = await client.query<transaction_completion>(
-      'SELECT * FROM dbos.transaction_completion WHERE workflow_id = $1 ORDER BY function_num',
-      [workflowID],
-    );
-    return rows;
-  } finally {
-    await client.end();
-  }
-}
-
-const probeState = { rows: [] as transaction_completion[] };
-
-// Reads back the checkpoints its transactions wrote, before completion clears them.
-async function checkpointProbeWorkflow(user: string) {
-  await regInsertFunction(user);
-  const error = await regErrorFunction(user).then(
-    () => undefined,
-    (e: Error) => e,
-  );
-  probeState.rows = await readCompletions(DBOS.workflowID!);
-  return error?.message;
-}
-
-const regCheckpointProbeWorkflow = DBOS.registerWorkflow(checkpointProbeWorkflow);
-
-const staleState = { originalOwner: null as string | null, completionsAtConflict: -1 };
-
-// Another execution claims the workflow while this transaction is still open.
-async function staleFunction() {
-  await NodePostgresDataSource.client.query("INSERT INTO race_side_effects(tag) VALUES ('stale')");
-  staleState.originalOwner = await setOwner(DBOS.workflowID!, 'another-execution');
-  return 'stale';
-}
-
-const regStaleFunction = dataSource.registerTransaction(staleFunction);
-
-async function staleWorkflow() {
-  try {
-    return await regStaleFunction();
-  } catch (e) {
-    if (!(e instanceof DBOSWorkflowConflictError)) throw e;
-    // Read before completion clears it: the conflict must not have been recorded as the step's outcome.
-    staleState.completionsAtConflict = (await readCompletions(DBOS.workflowID!)).length;
-    // A real duplicate parks here instead; reclaimed so this execution's outcome lands.
-    await setOwner(DBOS.workflowID!, staleState.originalOwner);
-    return 'conflicted';
-  }
-}
-
-const regStaleWorkflow = DBOS.registerWorkflow(staleWorkflow);
-
-const handOffState = { signal: () => {} };
-
-// Loses the workflow after its transaction, so its completion is a stale execution's.
-async function handOffWorkflow(user: string) {
-  const result = await regInsertFunction(user);
-  await setOwner(DBOS.workflowID!, 'another-execution');
-  handOffState.signal();
-  return result;
-}
-
-const regHandOffWorkflow = DBOS.registerWorkflow(handOffWorkflow);
-
-/** A promise with its resolver, so a test and a workflow can hand control back and forth. */
-function latch() {
-  let open = () => {};
-  const opened = new Promise<void>((resolve) => (open = resolve));
-  return { open, opened };
-}
-
-function newRewindState() {
-  return { atGate: latch(), release: latch(), blockerStarted: latch(), unblock: latch() };
-}
-
-let rewindState = newRewindState();
-
-// Waits after its transactions, so the test can cancel it with both checkpoints in place.
-async function gatedTwoInsertWorkflow(user: string) {
-  const first = await regInsertFunction(user);
-  const second = await regInsertFunction(user);
-  rewindState.atGate.open();
-  await rewindState.release.opened;
-  return [first.greet_count, second.greet_count];
-}
-
-const regGatedTwoInsertWorkflow = DBOS.registerWorkflow(gatedTwoInsertWorkflow);
-
-async function queueBlocker() {
-  rewindState.blockerStarted.open();
-  await rewindState.unblock.opened;
-}
-
-const regQueueBlocker = DBOS.registerWorkflow(queueBlocker);
-const regReadFunction = dataSource.registerTransaction(readFunction, { readOnly: true });
-
-class StaticClass {
-  static async insertFunction(user: string) {
-    return await insertFunction(user);
-  }
-
-  static async readFunction(user: string) {
-    return await readFunction(user);
-  }
-}
-
-StaticClass.insertFunction = dataSource.registerTransaction(StaticClass.insertFunction);
-StaticClass.readFunction = dataSource.registerTransaction(StaticClass.readFunction, { readOnly: true });
-
-class InstanceClass {
-  async insertFunction(user: string) {
-    return await insertFunction(user);
-  }
-
-  async readFunction(user: string) {
-    return await readFunction(user);
-  }
-}
-
-InstanceClass.prototype.insertFunction = dataSource.registerTransaction(
-  // eslint-disable-next-line @typescript-eslint/unbound-method
-  InstanceClass.prototype.insertFunction,
-);
-InstanceClass.prototype.readFunction = dataSource.registerTransaction(
-  // eslint-disable-next-line @typescript-eslint/unbound-method
-  InstanceClass.prototype.readFunction,
-  { readOnly: true },
-);
-
-async function insertWorkflowReg(user: string) {
-  return await regInsertFunction(user);
-}
-
-async function insertWorkflowRunTx(user: string) {
-  return await dataSource.runTransaction(() => insertFunction(user), { name: 'insertFunction' });
-}
-
-async function errorWorkflowReg(user: string) {
-  return await regErrorFunction(user);
-}
-
-async function errorWorkflowRunTx(user: string) {
-  return await dataSource.runTransaction(() => errorFunction(user), { name: 'errorFunction' });
-}
-
-async function readWorkflowReg(user: string) {
-  return await regReadFunction(user);
-}
-
-async function readWorkflowRunTx(user: string) {
-  return await dataSource.runTransaction(() => readFunction(user), { name: 'readFunction', readOnly: true });
-}
-
-async function staticWorkflow(user: string) {
-  const result = await StaticClass.insertFunction(user);
-  const readResult = await StaticClass.readFunction(user);
-  return [result, readResult];
-}
-
-async function instanceWorkflow(user: string) {
-  const instance = new InstanceClass();
-  const result = await instance.insertFunction(user);
-  const readResult = await instance.readFunction(user);
-  return [result, readResult];
-}
-
-const regInsertWorkflowReg = DBOS.registerWorkflow(insertWorkflowReg);
-const regInsertWorkflowRunTx = DBOS.registerWorkflow(insertWorkflowRunTx);
-const regErrorWorkflowReg = DBOS.registerWorkflow(errorWorkflowReg);
-const regErrorWorkflowRunTx = DBOS.registerWorkflow(errorWorkflowRunTx);
-const regReadWorkflowReg = DBOS.registerWorkflow(readWorkflowReg);
-const regReadWorkflowRunTx = DBOS.registerWorkflow(readWorkflowRunTx);
-const regStaticWorkflow = DBOS.registerWorkflow(staticWorkflow);
-const regInstanceWorkflow = DBOS.registerWorkflow(instanceWorkflow);
-
-describe('NodePostgresDataSourceCreateTxC', () => {
-  const userDB = new Pool(config);
-
-  beforeAll(async () => {
-    await createDatabases(userDB, false);
-  });
-
-  afterAll(async () => {
-    await userDB.end();
-  });
-
-  beforeEach(async () => {
-    DBOS.setConfig({ name: 'node-pg-ds-test' });
-    await DBOS.launch();
-  });
-
-  afterEach(async () => {
-    await DBOS.shutdown();
-  });
-
-  test('insert dataSource.register function', async () => {
-    const user = 'helloTest1';
-
-    await userDB.query('DELETE FROM greetings WHERE name = $1', [user]);
-    const workflowID = randomUUID();
-
-    await expect(DBOS.withNextWorkflowID(workflowID, () => regInsertWorkflowReg(user))).resolves.toMatchObject({
-      user,
-      greet_count: 1,
-    });
-
-    const { rows } = await userDB.query<transaction_completion>(
-      'SELECT * FROM dbos.transaction_completion WHERE workflow_id = $1',
-      [workflowID],
-    );
-    // Completion cleared the checkpoint the transaction wrote.
-    expect(rows).toHaveLength(0);
-  });
-});
-
-describe('NodePostgresDataSource migrations', () => {
-  const userDB = new Pool(config);
-
-  afterAll(async () => {
-    await userDB.end();
-  });
-
-  afterEach(async () => {
-    await DBOS.shutdown();
-  });
-
-  test('verify-only initialization requires the schema to be migrated out of band', async () => {
-    const suffix = randomUUID().replace(/-/g, '').slice(0, 8);
-    const schemaName = `ds_mig_${suffix}`;
-    const role = `ds_app_${suffix}`;
-    const admin = new Client({ ...config, database: 'postgres' });
-    await admin.connect();
-    try {
-      await ensureDB(admin, config.database);
-    } finally {
-      await admin.end();
-    }
-    await userDB.query(`CREATE ROLE "${role}"`);
-    try {
-      new NodePostgresDataSource(`verify-only-${suffix}`, config, schemaName, { runMigrations: false });
-      DBOS.setConfig({ name: 'node-pg-ds-test' });
-      await expect(DBOS.launch()).rejects.toThrow(/is at transaction schema version 0/);
-      await DBOS.shutdown();
-      const { rowCount } = await userDB.query('SELECT 1 FROM pg_namespace WHERE nspname = $1', [schemaName]);
-      expect(rowCount).toBe(0);
-
-      await NodePostgresDataSource.initializeDBOSSchema(config, schemaName, { applicationRole: role });
-      await DBOS.launch();
-      const { rows } = await userDB.query<{ allowed: boolean }>(
-        `SELECT has_table_privilege($1, $2, 'INSERT') AS allowed`,
-        [role, `"${schemaName}".transaction_completion`],
-      );
-      expect(rows).toEqual([{ allowed: true }]);
-    } finally {
-      await userDB.query(`DROP SCHEMA IF EXISTS "${schemaName}" CASCADE`);
-      await userDB.query(`DROP OWNED BY "${role}"`);
-      await userDB.query(`DROP ROLE "${role}"`);
-    }
-  });
-});

package/tests/test-helpers.ts

@@ -1,13 +0,0 @@
-import { Client } from 'pg';
-
-export async function ensureDB(client: Client, name: string) {
-  const results = await client.query('SELECT 1 FROM pg_database WHERE datname = $1', [name]);
-  if (results.rows.length === 0) {
-    await client.query(`CREATE DATABASE ${name}`);
-  }
-}
-
-export async function dropDB(client: Client, name: string, force: boolean = false) {
-  const withForce = force ? ' WITH (FORCE)' : '';
-  await client.query(`DROP DATABASE IF EXISTS ${name} ${withForce}`);
-}

package/tsconfig.json

@@ -1,9 +0,0 @@
-/* Visit https://aka.ms/tsconfig to read more about this file */
-{
-  "extends": "../../tsconfig.shared.json",
-  "compilerOptions": {
-    "outDir": "./dist"
-  },
-  "include": ["index.ts"],
-  "exclude": ["dist", "tests"]
-}