@opensaas/stack-core 0.23.0 → 0.25.0

package/src/config/types.ts

@@ -150,6 +150,125 @@ export type FieldAfterOperationHookArgs<
       context: import('../access/types.js').AccessContext
     }
 
+/**
+ * Arguments for field-level beforeTransaction hook (#590 / ADR-0010).
+ *
+ * Transaction-boundary hooks run OUTSIDE the write's database transaction.
+ * `beforeTransaction` runs before the transaction opens, so it has the input
+ * data but no persisted `item` yet (and, for create, no `item` to read). For
+ * update/delete the existing `item` is best-effort: present for the top-level
+ * target (which the pipeline resolves before opening the transaction) and
+ * `undefined` for nested targets (not resolved at the boundary to avoid
+ * pre-transaction reads). Use it for non-transactional side effects (e.g.
+ * external API calls) whose compensation pairs with `afterTransaction`.
+ */
+export type FieldBeforeTransactionHookArgs<
+  TTypeInfo extends TypeInfo,
+  TFieldKey extends FieldKeys<TTypeInfo['fields']> = FieldKeys<TTypeInfo['fields']>,
+> =
+  | {
+      listKey: string
+      fieldKey: TFieldKey
+      operation: 'create'
+      inputData: TTypeInfo['inputs']['create']
+      context: import('../access/types.js').AccessContext
+    }
+  | {
+      listKey: string
+      fieldKey: TFieldKey
+      operation: 'update'
+      inputData: TTypeInfo['inputs']['update']
+      item: TTypeInfo['item'] | undefined
+      context: import('../access/types.js').AccessContext
+    }
+  | {
+      listKey: string
+      fieldKey: TFieldKey
+      operation: 'delete'
+      item: TTypeInfo['item'] | undefined
+      context: import('../access/types.js').AccessContext
+    }
+
+/**
+ * Arguments for field-level afterTransaction hook (#590 / ADR-0010).
+ *
+ * Runs AFTER the transaction settles and ALWAYS runs when its paired
+ * `beforeTransaction` ran (symmetric bracket). The `status` discriminant tells
+ * the hook whether the write committed or rolled back:
+ *  - `committed`: the persisted `item`/`originalItem` are populated ONLY for the
+ *    TOP-LEVEL record of the write. For NESTED lists they are `undefined` — the
+ *    per-record persisted row is not reliably recoverable outside the
+ *    transaction, and these hooks fire at per-(list, operation) granularity, not
+ *    per record. For per-record nested compensation use the in-transaction
+ *    `afterOperation` (which receives the correct nested `item`).
+ *  - `rolled-back`: NO persisted `item`; the hook gets `inputData` and the
+ *    `error` that caused the rollback so it can compensate for whatever
+ *    `beforeTransaction` did externally.
+ */
+export type FieldAfterTransactionHookArgs<
+  TTypeInfo extends TypeInfo,
+  TFieldKey extends FieldKeys<TTypeInfo['fields']> = FieldKeys<TTypeInfo['fields']>,
+> =
+  | {
+      listKey: string
+      fieldKey: TFieldKey
+      operation: 'create'
+      status: 'committed'
+      inputData: TTypeInfo['inputs']['create']
+      /** Persisted row — populated for the top-level list only; `undefined` for nested lists. */
+      item: TTypeInfo['item'] | undefined
+      context: import('../access/types.js').AccessContext
+    }
+  | {
+      listKey: string
+      fieldKey: TFieldKey
+      operation: 'create'
+      status: 'rolled-back'
+      inputData: TTypeInfo['inputs']['create']
+      error: unknown
+      context: import('../access/types.js').AccessContext
+    }
+  | {
+      listKey: string
+      fieldKey: TFieldKey
+      operation: 'update'
+      status: 'committed'
+      inputData: TTypeInfo['inputs']['update']
+      /** Pre-write row — populated for the top-level list only; `undefined` for nested lists. */
+      originalItem: TTypeInfo['item'] | undefined
+      /** Persisted row — populated for the top-level list only; `undefined` for nested lists. */
+      item: TTypeInfo['item'] | undefined
+      context: import('../access/types.js').AccessContext
+    }
+  | {
+      listKey: string
+      fieldKey: TFieldKey
+      operation: 'update'
+      status: 'rolled-back'
+      inputData: TTypeInfo['inputs']['update']
+      originalItem: TTypeInfo['item'] | undefined
+      error: unknown
+      context: import('../access/types.js').AccessContext
+    }
+  | {
+      listKey: string
+      fieldKey: TFieldKey
+      operation: 'delete'
+      status: 'committed'
+      /** Pre-write row — populated for the top-level list only; `undefined` for nested lists. */
+      originalItem: TTypeInfo['item'] | undefined
+      context: import('../access/types.js').AccessContext
+    }
+  | {
+      listKey: string
+      fieldKey: TFieldKey
+      operation: 'delete'
+      status: 'rolled-back'
+      originalItem: TTypeInfo['item'] | undefined
+      error: unknown
+      context: import('../access/types.js').AccessContext
+    }
+
 /**
  * Arguments for field-level resolveOutput hook
  * Used to transform field values after database read
@@ -278,6 +397,53 @@ export type FieldHooks<
    */
   afterOperation?: (args: FieldAfterOperationHookArgs<TTypeInfo, TFieldKey>) => Promise<void> | void
 
+  /**
+   * Perform side effects BEFORE the write's database transaction opens
+   * (#590 / ADR-0010 transaction-boundary hook).
+   *
+   * Unlike `beforeOperation` (which runs INSIDE the transaction and rolls back
+   * with it), this runs OUTSIDE the transaction — use it for non-transactional
+   * side effects such as external API calls that must not hold a DB transaction
+   * open and cannot be rolled back. If this throws, the write is aborted (the
+   * transaction never opens) and the paired `afterTransaction` fires with
+   * `status: 'rolled-back'`.
+   *
+   * @example
+   * ```typescript
+   * beforeTransaction: async ({ operation, inputData }) => {
+   *   await externalApi.reserve(inputData.externalId)
+   * }
+   * ```
+   */
+  beforeTransaction?: (
+    args: FieldBeforeTransactionHookArgs<TTypeInfo, TFieldKey>,
+  ) => Promise<void> | void
+
+  /**
+   * Perform side effects AFTER the write's database transaction settles
+   * (#590 / ADR-0010 transaction-boundary hook).
+   *
+   * ALWAYS runs when the paired `beforeTransaction` ran (symmetric bracket),
+   * receiving `status: 'committed' | 'rolled-back'`. On `committed` it gets the
+   * persisted `item` ONLY for the top-level record (`undefined` for nested
+   * lists — use the in-transaction `afterOperation` for per-record nested
+   * compensation); on `rolled-back` it gets the `error` that caused the
+   * rollback and NO `item`, so it can compensate for whatever `beforeTransaction`
+   * did externally.
+   *
+   * @example
+   * ```typescript
+   * afterTransaction: async (args) => {
+   *   if (args.status === 'rolled-back') {
+   *     await externalApi.release(args.inputData.externalId)
+   *   }
+   * }
+   * ```
+   */
+  afterTransaction?: (
+    args: FieldAfterTransactionHookArgs<TTypeInfo, TFieldKey>,
+  ) => Promise<void> | void
+
   /**
    * Transform field value after database read
    * Called when returning results from query operations
@@ -1269,6 +1435,117 @@ export type AfterOperationHookArgs<
       context: import('../access/types.js').AccessContext
     }
 
+/**
+ * Hook arguments for the list-level beforeTransaction hook (#590 / ADR-0010).
+ *
+ * Runs BEFORE the write's transaction opens (outside it). Has input data but no
+ * persisted `item`. For update/delete the existing `item` is best-effort:
+ * present for the top-level target (resolved before the transaction opens) and
+ * `undefined` for nested targets. For non-transactional side effects whose
+ * compensation pairs with `afterTransaction`.
+ */
+export type BeforeTransactionHookArgs<
+  TOutput = Record<string, unknown>,
+  TCreateInput = Record<string, unknown>,
+  TUpdateInput = Record<string, unknown>,
+> =
+  | {
+      listKey: string
+      operation: 'create'
+      inputData: TCreateInput
+      context: import('../access/types.js').AccessContext
+    }
+  | {
+      listKey: string
+      operation: 'update'
+      inputData: TUpdateInput
+      item: TOutput | undefined
+      context: import('../access/types.js').AccessContext
+    }
+  | {
+      listKey: string
+      operation: 'delete'
+      item: TOutput | undefined
+      context: import('../access/types.js').AccessContext
+    }
+
+/**
+ * Hook arguments for the list-level afterTransaction hook (#590 / ADR-0010).
+ *
+ * Runs AFTER the write's transaction settles and ALWAYS runs when the paired
+ * `beforeTransaction` ran (symmetric bracket). The `status` discriminant tells
+ * the hook whether the write committed or rolled back:
+ *  - `committed`: the persisted `item`/`originalItem` are populated ONLY for the
+ *    TOP-LEVEL record of the write. For NESTED lists they are `undefined` — the
+ *    per-record persisted row is not reliably recoverable outside the
+ *    transaction (recovering it would duplicate #569's in-transaction id-diff
+ *    machinery), and these hooks fire at per-(list, operation) granularity, not
+ *    per record. For per-record nested compensation use the in-transaction
+ *    `afterOperation` (which receives the correct nested `item`);
+ *    transaction-boundary hooks are for external-call compensation keyed off
+ *    `status`/`inputData`.
+ *  - `rolled-back`: NO persisted `item`; the hook gets `inputData` and the
+ *    `error` that caused the rollback so it can compensate.
+ */
+export type AfterTransactionHookArgs<
+  TOutput = Record<string, unknown>,
+  TCreateInput = Record<string, unknown>,
+  TUpdateInput = Record<string, unknown>,
+> =
+  | {
+      listKey: string
+      operation: 'create'
+      status: 'committed'
+      inputData: TCreateInput
+      /** Persisted row — populated for the top-level list only; `undefined` for nested lists. */
+      item: TOutput | undefined
+      context: import('../access/types.js').AccessContext
+    }
+  | {
+      listKey: string
+      operation: 'create'
+      status: 'rolled-back'
+      inputData: TCreateInput
+      error: unknown
+      context: import('../access/types.js').AccessContext
+    }
+  | {
+      listKey: string
+      operation: 'update'
+      status: 'committed'
+      inputData: TUpdateInput
+      /** Pre-write row — populated for the top-level list only; `undefined` for nested lists. */
+      originalItem: TOutput | undefined
+      /** Persisted row — populated for the top-level list only; `undefined` for nested lists. */
+      item: TOutput | undefined
+      context: import('../access/types.js').AccessContext
+    }
+  | {
+      listKey: string
+      operation: 'update'
+      status: 'rolled-back'
+      inputData: TUpdateInput
+      originalItem: TOutput | undefined
+      error: unknown
+      context: import('../access/types.js').AccessContext
+    }
+  | {
+      listKey: string
+      operation: 'delete'
+      status: 'committed'
+      /** Pre-write row — populated for the top-level list only; `undefined` for nested lists. */
+      originalItem: TOutput | undefined
+      context: import('../access/types.js').AccessContext
+    }
+  | {
+      listKey: string
+      operation: 'delete'
+      status: 'rolled-back'
+      originalItem: TOutput | undefined
+      error: unknown
+      context: import('../access/types.js').AccessContext
+    }
+
 export type Hooks<
   TOutput = Record<string, unknown>,
   TCreateInput = Record<string, unknown>,
@@ -1284,6 +1561,26 @@ export type Hooks<
   afterOperation?: (
     args: AfterOperationHookArgs<TOutput, TCreateInput, TUpdateInput>,
   ) => Promise<void>
+  /**
+   * Side effect BEFORE the write's transaction opens (#590 / ADR-0010).
+   * Runs OUTSIDE the transaction — for non-transactional work (external API
+   * calls). Throwing aborts the write; the paired `afterTransaction` then fires
+   * with `status: 'rolled-back'`. See {@link BeforeTransactionHookArgs}.
+   */
+  beforeTransaction?: (
+    args: BeforeTransactionHookArgs<TOutput, TCreateInput, TUpdateInput>,
+  ) => Promise<void> | void
+  /**
+   * Side effect AFTER the write's transaction settles (#590 / ADR-0010).
+   * ALWAYS runs when `beforeTransaction` ran; receives `committed | rolled-back`
+   * + `error`. The persisted `item`/`originalItem` are present only on commit
+   * AND only for the top-level record (`undefined` for nested lists). The
+   * compensation half of the transaction-boundary bracket. See
+   * {@link AfterTransactionHookArgs}.
+   */
+  afterTransaction?: (
+    args: AfterTransactionHookArgs<TOutput, TCreateInput, TUpdateInput>,
+  ) => Promise<void> | void
   /**
    * @deprecated Use 'validate' instead. This alias is provided for backwards compatibility.
    */
@@ -1402,6 +1699,68 @@ export type ListConfig<TTypeInfo extends TypeInfo> = {
          */
         autoCreate?: boolean
       }
+  /**
+   * UI configuration for this list (admin interface).
+   *
+   * Mirrors Keystone's list-level `ui` block. Currently only `listView`
+   * defaults (columns + sort) are supported.
+   */
+  ui?: ListUIConfig
+}
+
+/**
+ * List-level UI configuration for the admin interface.
+ *
+ * Mirrors Keystone's `ui` block on a list. Only the list-view defaults
+ * (column selection/order and default sort) are supported today; other
+ * Keystone concerns (`label`, `labelField`, `description`) are intentionally
+ * deferred as they cover different concerns (navigation text and
+ * relationship-picker labels rather than list-view defaults).
+ */
+export type ListUIConfig = {
+  /**
+   * Default list-view (table) configuration for this list, mirroring
+   * Keystone's `ui.listView`.
+   */
+  listView?: ListViewUIConfig
+}
+
+/**
+ * Default list-view (table) configuration for a list, mirroring Keystone's
+ * `ui.listView`.
+ *
+ * When omitted, the admin UI falls back to its existing defaults: every
+ * non-system field is shown as a column and no default sort is applied.
+ */
+export type ListViewUIConfig = {
+  /**
+   * The fields to show as columns in the list table, in order.
+   *
+   * Drives both the column **selection** and their **order**. When omitted,
+   * all non-system fields are shown (current default behaviour).
+   *
+   * @example
+   * ```typescript
+   * ui: { listView: { initialColumns: ['title', 'status', 'author'] } }
+   * ```
+   */
+  initialColumns?: string[]
+  /**
+   * The default sort applied to the list table.
+   *
+   * When omitted, no default sort is applied (current default behaviour).
+   *
+   * @example
+   * ```typescript
+   * ui: { listView: { initialSort: { field: 'createdAt', direction: 'desc' } } }
+   * ```
+   */
+  initialSort?: {
+    /** The field to sort by. Must be a field defined on the list. */
+    field: string
+    /** The sort direction. */
+    direction: 'asc' | 'desc'
+  }
 }
 
 /**
@@ -1611,6 +1970,40 @@ export type DatabaseConfig = {
    * ```
    */
   extendPrismaSchema?: (schema: string) => string
+  /**
+   * Override the Prisma `generator client { ... }` options the CLI emits for the
+   * `.opensaas` prisma-client subtree.
+   *
+   * By default the generator emits `importFileExtension = "ts"` and
+   * `moduleFormat = "esm"` so the whole generated bundle is statically
+   * resolvable and matches the explicit `.ts` import-extension style the rest of
+   * the `.opensaas` bundle uses (see ADR-0008). Supply this option only when you
+   * need a different module/extension story (e.g. emitting `.js` extensions for a
+   * Node-only consumer). Any value you provide wins; omitted keys fall back to
+   * the `ts`/`esm` defaults.
+   *
+   * @example Emit `.js` extensions and CommonJS for a plain-Node consumer
+   * ```typescript
+   * db: {
+   *   provider: 'postgresql',
+   *   prismaGeneratorOptions: {
+   *     importFileExtension: 'js',
+   *     moduleFormat: 'commonjs',
+   *   },
+   *   // ... rest of config
+   * }
+   * ```
+   */
+  prismaGeneratorOptions?: {
+    /**
+     * Value for the generator's `importFileExtension` option. Defaults to `'ts'`.
+     */
+    importFileExtension?: 'ts' | 'js'
+    /**
+     * Value for the generator's `moduleFormat` option. Defaults to `'esm'`.
+     */
+    moduleFormat?: 'esm' | 'commonjs'
+  }
 }
 
 /**
@@ -2096,6 +2489,39 @@ export interface OutputConfig {
    * @default ".opensaas"
    */
   opensaasDir?: string
+  /**
+   * Opt in to an additional **Node build** of the Generated bundle.
+   *
+   * By default (omitted) the generator emits only the bundler-loadable `.ts`
+   * form (ADR-0008): TypeScript with explicit `.ts` import extensions, traced
+   * and transpiled by the host's bundler. That form cannot execute under plain
+   * Node, so a live module that must run in BOTH a bundled and a bundler-less
+   * runtime (e.g. better-auth's Prisma adapter, imported by the Next server AND
+   * by a Playwright e2e helper or a build-time script) has no Node-loadable
+   * entry to point at.
+   *
+   * Setting `buildTarget: 'node'` additionally compiles the bundle to a
+   * plain-Node-loadable ESM form under `<opensaasDir>/dist/` (`.js` + `.d.ts`,
+   * with a `{"type":"module"}` marker). The compiled entry is
+   * `<opensaasDir>/dist/context.js`; a portable module imports it directly so
+   * the bundler traces it AND plain Node executes it (one specifier, both
+   * runtimes — see ADR-0011). The default `.ts` form is unchanged and still
+   * emitted; the Node build is purely additive.
+   *
+   * `'node'` is the only target today. The field is a string-literal union so
+   * future compiled targets can be added without a breaking change.
+   *
+   * @example
+   * ```typescript
+   * export default config({
+   *   output: { buildTarget: 'node' },
+   *   // ...
+   * })
+   * // Then import the compiled entry from a plain-Node consumer:
+   * //   const { rawOpensaasContext } = await import('./.opensaas/dist/context.js')
+   * ```
+   */
+  buildTarget?: 'node'
 }
 
 export interface OpenSaasConfig {