@opensaas/stack-core 0.24.0 → 0.26.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.
    */
@@ -1673,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'
+  }
 }
 
 /**
@@ -2158,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 {

package/src/context/apply-defaults.ts

@@ -0,0 +1,79 @@
+import type { FieldConfig } from '../config/types.js'
+
+/**
+ * Apply field `defaultValue`s to omitted inputs on CREATE — the runtime half of
+ * the resolve-then-validate ordering (Keystone 6 parity, issue #615).
+ *
+ * A field's `defaultValue` is otherwise only realised as a Prisma `@default(...)`
+ * applied by the database at write time, which is AFTER the write pipeline's
+ * validation phase has already run. That ordering means a required-with-default
+ * field (e.g. `select({ validation: { isRequired: true }, defaultValue: 'X' })`)
+ * fails `isRequired` validation on an omitted input even though a default exists.
+ *
+ * This helper closes that gap: in the resolve phase (after `resolveInput` hooks,
+ * before validation) it fills `resolvedData[field]` with the field's
+ * `defaultValue` ONLY when the field was OMITTED (value is `undefined`). It is a
+ * SINGLE shared mechanism used by both the top-level create path (Hook Pipeline)
+ * and the nested-relation create path.
+ *
+ * Guard rails (each acceptance-criteria-driven):
+ *   - CREATE only. Update never injects defaults for omitted fields (the caller
+ *     only invokes this for `operation === 'create'`).
+ *   - Explicitly-provided values are preserved. A key present in `resolvedData`
+ *     — INCLUDING an explicit `null` — is left untouched; only `undefined`
+ *     (omitted) keys are filled.
+ *   - Virtual, system (`id`/`createdAt`/`updatedAt`) and relationship fields are
+ *     skipped — they have no scalar `defaultValue` to inject and relationships
+ *     carry connect/create payloads rather than literal defaults.
+ *   - The timestamp `{ kind: 'now' }` sentinel is NOT injected: it is not a
+ *     literal value but a request for the DB-level `@default(now())`, which still
+ *     applies at write time. Injecting the sentinel object would corrupt the
+ *     payload. (A concrete `Date` default is a real literal and IS injected.)
+ *
+ * The function mutates and returns `resolvedData` (consistent with the other
+ * resolve-phase helpers that thread `resolvedData` through the pipeline).
+ */
+export function applyCreateDefaults(
+  resolvedData: Record<string, unknown>,
+  fieldConfigs: Record<string, FieldConfig>,
+): Record<string, unknown> {
+  for (const [fieldKey, fieldConfig] of Object.entries(fieldConfigs)) {
+    // Skip virtual fields — not stored in the database.
+    if (fieldConfig.virtual) continue
+
+    // Skip system fields — always managed by the framework/DB.
+    if (fieldKey === 'id' || fieldKey === 'createdAt' || fieldKey === 'updatedAt') continue
+
+    // Skip relationships — they carry connect/create payloads, not literal defaults.
+    if (fieldConfig.type === 'relationship') continue
+
+    // No declared default → nothing to inject.
+    if (!('defaultValue' in fieldConfig) || fieldConfig.defaultValue === undefined) continue
+
+    // Only fill OMITTED keys. An explicitly-provided value (including explicit
+    // `null`) is preserved and must not be overwritten by the default.
+    if (resolvedData[fieldKey] !== undefined) continue
+
+    const defaultValue = fieldConfig.defaultValue
+
+    // The timestamp `{ kind: 'now' }` sentinel is a DB-level `@default(now())`
+    // request, not a literal — leave it for Prisma to apply at write time.
+    if (isNowSentinel(defaultValue)) continue
+
+    resolvedData[fieldKey] = defaultValue
+  }
+
+  return resolvedData
+}
+
+/**
+ * Detect the timestamp `{ kind: 'now' }` default sentinel.
+ */
+function isNowSentinel(value: unknown): boolean {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'kind' in value &&
+    (value as { kind: unknown }).kind === 'now'
+  )
+}

package/src/context/hook-pipeline.ts

@@ -8,6 +8,7 @@ import {
   validateFieldRules,
   ValidationError,
 } from '../hooks/index.js'
+import { applyCreateDefaults } from './apply-defaults.js'
 
 /**
  * Hook Pipeline — the single module that runs the transform+validate span of a
@@ -109,6 +110,16 @@ async function runHookPipeline(args: HookPipelineArgs): Promise<HookPipelineResu
     item,
   )
 
+  // ── Phase 1.75: apply field defaults to omitted inputs (CREATE only) ───────
+  // Resolve-then-validate (Keystone parity, #615): a field declaring a
+  // `defaultValue` is filled into `resolvedData` here — AFTER resolveInput hooks
+  // and BEFORE validation — but only when the field was OMITTED, so a
+  // required-with-default field passes `isRequired` instead of failing it.
+  // Update is untouched (no default injection on update).
+  if (operation === 'create') {
+    resolvedData = applyCreateDefaults(resolvedData, listConfig.fields)
+  }
+
   // ── Phase 2: list-level validate ──────────────────────────────────────────
   await executeValidate(
     listConfig.hooks,