@dbos-inc/typeorm-datasource 5.3.4-preview → 5.3.5-preview

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dbos-inc/typeorm-datasource",
-  "version": "5.3.4-preview",
+  "version": "5.3.5-preview",
   "description": "DBOS DataSource library for TypeORM with PostgreSQL support",
   "license": "MIT",
   "main": "dist/index.js",
@@ -16,9 +16,9 @@
     "test": "npm run build && jest --detectOpenHandles"
   },
   "dependencies": {
-    "typeorm": "^0.3.24",
     "pg": "^8.11.3",
-    "superjson": "^1.13"
+    "superjson": "^1.13",
+    "typeorm": "^0.3.24"
   },
   "peerDependencies": {
     "@dbos-inc/dbos-sdk": "*"

package/index.ts

@@ -1,424 +0,0 @@
-import { PoolConfig } from 'pg';
-import { DBOS, FunctionName } from '@dbos-inc/dbos-sdk';
-import {
-  type DataSourceTransactionHandler,
-  isPGRetriableTransactionError,
-  DBOSError,
-  DBOSStepAlreadyRecordedError,
-  DBOSWorkflowConflictError,
-  assertStillOwnsWorkflow,
-  replayRecordedStep,
-  registerTransaction,
-  runTransaction,
-  DBOSDataSource,
-  registerDataSource,
-  PGTransactionConfig,
-  DataSourceMigrationOptions,
-  DataSourceSQLExecutor,
-  initializeDataSourceSchemaPG,
-  migrateDataSourcePG,
-  verifyDataSourcePG,
-} from '@dbos-inc/dbos-sdk/datasource';
-import { DataSource, EntityManager } from 'typeorm';
-import type { PostgresConnectionOptions } from 'typeorm/driver/postgres/PostgresConnectionOptions';
-import { AsyncLocalStorage } from 'async_hooks';
-import { SuperJSON } from 'superjson';
-
-export interface TypeORMTransactionConfig extends PGTransactionConfig {
-  name?: string;
-}
-
-interface DBOSTypeOrmLocalCtx {
-  entityManager: EntityManager;
-  owner: TypeOrmTransactionHandler;
-}
-
-const asyncLocalCtx = new AsyncLocalStorage<DBOSTypeOrmLocalCtx>();
-
-function typeOrmExecutor(db: DataSource | EntityManager): DataSourceSQLExecutor {
-  return async (sql) => await db.query<Record<string, unknown>[]>(sql);
-}
-
-interface transaction_completion {
-  workflow_id: string;
-  function_num: number;
-  output: string | null;
-  error: string | null;
-}
-
-class TypeOrmTransactionHandler implements DataSourceTransactionHandler {
-  #createdDataSource: DataSource | undefined;
-  readonly schemaName: string;
-
-  constructor(
-    readonly name: string,
-    private readonly config?: PoolConfig,
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
-    private readonly entities?: Function[],
-    private readonly providedDataSource?: DataSource,
-    schemaName: string = 'dbos',
-    private readonly options: DataSourceMigrationOptions = {},
-  ) {
-    this.schemaName = schemaName;
-  }
-
-  static async createDataSource(
-    config: PoolConfig,
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
-    entities: Function[],
-  ): Promise<DataSource> {
-    const ds = new DataSource({
-      type: 'postgres',
-      entities: entities,
-      url: config.connectionString,
-      host: config.host,
-      port: config.port,
-      username: config.user,
-      // TypeORM passes password and ssl to pg unchanged but types them more narrowly than pg does.
-      password: config.password as PostgresConnectionOptions['password'],
-      database: config.database,
-      ssl: config.ssl as PostgresConnectionOptions['ssl'],
-      connectTimeoutMS: config.connectionTimeoutMillis,
-      poolSize: config.max,
-    });
-    await ds.initialize();
-    return ds;
-  }
-
-  get dataSource(): DataSource {
-    const ds = this.providedDataSource ?? this.#createdDataSource;
-    if (!ds) {
-      throw new Error(`DataSource ${this.name} is not initialized.`);
-    }
-    return ds;
-  }
-
-  async initialize(): Promise<void> {
-    if (!this.providedDataSource) {
-      const ds = this.#createdDataSource;
-      this.#createdDataSource = await TypeOrmTransactionHandler.createDataSource(this.config!, this.entities!);
-      await ds?.destroy();
-    }
-
-    if (this.options.runMigrations === false) {
-      await verifyDataSourcePG(typeOrmExecutor(this.dataSource), this.schemaName, this.name);
-      return;
-    }
-
-    try {
-      await this.dataSource.transaction((em) => migrateDataSourcePG(typeOrmExecutor(em), this.schemaName));
-    } catch (err) {
-      throw new Error(
-        `In initialization of 'TypeOrmDataSource' ${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 ds = this.#createdDataSource;
-    this.#createdDataSource = undefined;
-    await ds?.destroy();
-  }
-
-  async deleteCheckpoints(workflowID: string, startStep: number, beforeCommit?: () => Promise<void>): Promise<void> {
-    await this.dataSource.transaction(async (entityManager: EntityManager) => {
-      await entityManager.query(
-        `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 TxOutputRow = Pick<transaction_completion, 'output' | 'error'>;
-    const rows = await this.dataSource.query<TxOutputRow[]>(
-      `SELECT output, error FROM "${this.schemaName}".transaction_completion
-       WHERE workflow_id=$1 AND function_num=$2;`,
-      [workflowID, stepID],
-    );
-
-    if (rows.length !== 1) {
-      return undefined;
-    }
-
-    const { output, error } = rows[0];
-    return error !== null ? { error } : { output };
-  }
-
-  static async #recordOutput(
-    entityManager: EntityManager,
-    workflowID: string,
-    stepID: number,
-    output: string,
-    schemaName: string,
-  ): Promise<void> {
-    const rows = await entityManager.query<{ workflow_id: string }[]>(
-      `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.dataSource.query<{ workflow_id: string }[]>(
-      `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);
-  }
-
-  /* Required by base class */
-  async invokeTransactionFunction<This, Args extends unknown[], Return>(
-    config: PGTransactionConfig | 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 isolationLevel = config?.isolationLevel ?? 'READ COMMITTED';
-    const readOnly = config?.readOnly ? true : 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.dataSource.transaction(isolationLevel, async (entityManager: EntityManager) => {
-          if (readOnly) {
-            await entityManager.query('SET TRANSACTION READ ONLY');
-          }
-
-          const result = await asyncLocalCtx.run({ entityManager, owner: this }, async () => {
-            return await func.call(target, ...args);
-          });
-
-          // save the output of read/write transactions
-          if (saveResults) {
-            await TypeOrmTransactionHandler.#recordOutput(
-              entityManager,
-              workflowID,
-              stepID!,
-              SuperJSON.stringify(result),
-              this.schemaName,
-            );
-          }
-
-          return result;
-        });
-
-        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());
-          // Retry serialization failures.
-          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 TypeOrmDataSource implements DBOSDataSource<TypeORMTransactionConfig> {
-  // User calls this... DBOS not directly involved...
-  static #getEntityManager(p?: TypeOrmTransactionHandler): EntityManager {
-    if (!DBOS.isInTransaction()) {
-      throw new Error('Invalid use of TypeOrmDataSource.entityManager outside of a DBOS transaction');
-    }
-    const ctx = asyncLocalCtx.getStore();
-    if (!ctx) {
-      throw new Error('Invalid use of TypeOrmDataSource.entityManager outside of a DBOS transaction');
-    }
-    if (p && p !== ctx.owner) {
-      throw new Error('Invalid retrieval of `TypeOrmDataSource.entityManager` from the wrong instance');
-    }
-
-    return ctx.entityManager;
-  }
-
-  static get entityManager() {
-    return TypeOrmDataSource.#getEntityManager(undefined);
-  }
-
-  get entityManager() {
-    return TypeOrmDataSource.#getEntityManager(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: PoolConfig,
-    schemaName: string = 'dbos',
-    options: { applicationRole?: string } = {},
-  ): Promise<void> {
-    const ds = await TypeOrmTransactionHandler.createDataSource(config, []);
-    try {
-      await ds.transaction((em) =>
-        initializeDataSourceSchemaPG(typeOrmExecutor(em), schemaName, options.applicationRole),
-      );
-    } finally {
-      await ds.destroy();
-    }
-  }
-
-  #provider: TypeOrmTransactionHandler;
-
-  private constructor(
-    readonly name: string,
-    config?: PoolConfig,
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
-    entities?: Function[],
-    dataSource?: DataSource,
-    schemaName: string = 'dbos',
-    options: DataSourceMigrationOptions = {},
-  ) {
-    if (config && entities) {
-      this.#provider = new TypeOrmTransactionHandler(name, config, entities, undefined, schemaName, options);
-      registerDataSource(this.#provider);
-    } else if (dataSource) {
-      this.#provider = new TypeOrmTransactionHandler(name, undefined, undefined, dataSource, schemaName, options);
-      registerDataSource(this.#provider);
-    } else {
-      throw new TypeError(
-        'TypeOrmDataSource must be provided with the underlying `DataSource` or with a configuration and entity list',
-      );
-    }
-  }
-
-  static createFromConfig(
-    name: string,
-    config: PoolConfig,
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
-    entities: Function[],
-    schemaName: string = 'dbos',
-    options: DataSourceMigrationOptions = {},
-  ) {
-    return new TypeOrmDataSource(name, config, entities, undefined, schemaName, options);
-  }
-
-  static createFromDataSource(
-    name: string,
-    ds: DataSource,
-    schemaName: string = 'dbos',
-    options: DataSourceMigrationOptions = {},
-  ) {
-    return new TypeOrmDataSource(name, undefined, undefined, ds, schemaName, options);
-  }
-
-  /**
-   * Run `func` as a transaction against this DataSource
-   * @param func Function to run within a transactional context
-   * @param funcName Name to record for the transaction
-   * @param config Transaction configuration (isolation, etc)
-   * @returns Return value from `func`
-   */
-  async runTransaction<T>(func: () => Promise<T>, config?: TypeORMTransactionConfig) {
-    return await runTransaction(func, config?.name ?? func.name, { dsName: this.name, config });
-  }
-
-  /**
-   * Register function as DBOS transaction, to be called within the context
-   *  of a transaction on this data source.
-   *
-   * @param func Function to wrap
-   * @param target Name of function
-   * @param config Transaction settings
-   * @returns Wrapped function, to be called instead of `func`
-   */
-  registerTransaction<This, Args extends unknown[], Return>(
-    func: (this: This, ...args: Args) => Promise<Return>,
-    config?: TypeORMTransactionConfig & FunctionName,
-  ): (this: This, ...args: Args) => Promise<Return> {
-    return registerTransaction(this.name, func, config);
-  }
-
-  /**
-   * Decorator establishing function as a transaction
-   */
-  transaction(config?: TypeORMTransactionConfig) {
-    // 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 new 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,60 +0,0 @@
-import { Client } from 'pg';
-import { TypeOrmDataSource } from '../index';
-import { dropDB, ensureDB } from './test-helpers';
-
-describe('TypeOrmDataSource.configure', () => {
-  const config = { user: 'postgres', database: 'typeorm_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 TypeOrmDataSource.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();
-    }
-  });
-
-  describe('connection settings', () => {
-    const password = process.env['PGPASSWORD'] || 'dbos';
-    const savedEnv = { PGPASSWORD: process.env['PGPASSWORD'], PGPASSFILE: process.env['PGPASSFILE'] };
-
-    // Hide the password from the environment and ~/.pgpass, so only the configured one can authenticate.
-    beforeEach(() => {
-      delete process.env['PGPASSWORD'];
-      process.env['PGPASSFILE'] = '/nonexistent/pgpass';
-    });
-
-    afterEach(() => {
-      for (const [key, value] of Object.entries(savedEnv)) {
-        if (value === undefined) delete process.env[key];
-        else process.env[key] = value;
-      }
-    });
-
-    test('uses the configured password', async () => {
-      await expect(TypeOrmDataSource.initializeDBOSSchema({ ...config, password })).resolves.toBeUndefined();
-    });
-
-    test('uses the configured ssl setting', async () => {
-      // Fails either way SSL is attempted: a server without SSL refuses it, and a local server's certificate is self-signed.
-      await expect(
-        TypeOrmDataSource.initializeDBOSSchema({ ...config, password, ssl: { rejectUnauthorized: true } }),
-      ).rejects.toThrow(/SSL|certificate/);
-    });
-  });
-});