@rvoh/dream 2.8.0 → 2.9.0

package/dist/esm/src/ops/index.js

@@ -63,17 +63,38 @@ const ops = {
      * Creates an `OpsStatement` using the SQL `LIKE` operator for case-sensitive pattern matching.
      * Use `%` as a wildcard in the pattern string.
      *
+     * **User-supplied patterns:** the value is bound as a parameter (no SQL
+     * injection), but `%`, `_`, and `\` in the bound value are still interpreted
+     * as wildcards by the SQL engine. Wrap user input with `ops.like.escape`
+     * if you need literal matching:
+     *
+     *     User.where({ name: ops.like(`%${ops.like.escape(query)}%`) })
+     *
+     * `ops.like.escape` escapes the three metacharacters that PostgreSQL's
+     * `LIKE` / `ILIKE` operators treat as wildcards (`\`, `%`, `_`) so the
+     * returned string matches literally. The same helper applies to all four
+     * LIKE-family ops (`like`, `ilike`, `not.like`, `not.ilike`); it is exposed
+     * here as the canonical entry point. If a caller uses `ESCAPE '...'` with
+     * a non-default character this helper will not be appropriate.
+     *
      * @param like - The pattern string (e.g. `'%hello%'`).
      * @returns An `OpsStatement` using the `like` operator.
      *
      * @example
      * User.where({ name: ops.like('%alice%') })
      */
-    like: (like) => new OpsStatement('like', like),
+    like: Object.assign((like) => new OpsStatement('like', like), {
+        escape: (input) => input.replace(/\\/g, '\\\\').replace(/%/g, '\\%').replace(/_/g, '\\_'),
+    }),
     /**
      * Creates an `OpsStatement` using the SQL `ILIKE` operator for case-insensitive pattern matching.
      * Use `%` as a wildcard in the pattern string.
      *
+     * **User-supplied patterns:** the value is bound as a parameter (no SQL
+     * injection), but `%`, `_`, and `\` in the bound value are still interpreted
+     * as wildcards by the SQL engine. Wrap user input with `ops.like.escape`
+     * if you need literal matching.
+     *
      * @param ilike - The pattern string (e.g. `'%hello%'`).
      * @returns An `OpsStatement` using the `ilike` operator.
      *
@@ -201,6 +222,9 @@ const ops = {
         /**
          * Creates an `OpsStatement` using the `NOT LIKE` operator for case-sensitive pattern exclusion.
          *
+         * **User-supplied patterns:** see the note on `ops.like`. Wrap user input
+         * with `ops.like.escape` for literal matching.
+         *
          * @param like - The pattern string (e.g. `'%spam%'`).
          * @returns An `OpsStatement` using the `not like` operator.
          *
@@ -211,6 +235,9 @@ const ops = {
         /**
          * Creates an `OpsStatement` using the `NOT ILIKE` operator for case-insensitive pattern exclusion.
          *
+         * **User-supplied patterns:** see the note on `ops.ilike`. Wrap user input
+         * with `ops.like.escape` for literal matching.
+         *
          * @param ilike - The pattern string (e.g. `'%spam%'`).
          * @returns An `OpsStatement` using the `not ilike` operator.
          *

package/dist/esm/src/serializer/builders/DreamSerializerBuilder.js

@@ -20,14 +20,27 @@ export default class DreamSerializerBuilder {
     /**
      * Includes an attribute from a nested object in the serialized output.
      *
-     * Accesses `targetName.name` on the data object. If the target object
-     * or the delegated attribute is null/undefined, the `default` option value
-     * will be used if provided.
+     * Accesses `targetName.name` on the data object. When the target object or the
+     * delegated attribute is null/undefined, the resolution order is:
+     *   1. `default` if provided → renders the default value
+     *   2. `required: false` → omits the key entirely from the rendered output
+     *   3. otherwise → renders `null`
      *
      * When the target is a Dream model, OpenAPI types may be automatically inferred
      * for standard database columns. For json/jsonb columns or non-Dream targets,
      * the `openapi` option is required.
      *
+     * `optional` and `required` are not aliases — they encode different things and can
+     * be used together:
+     *   - `optional: true` is an OpenAPI-only marker (no runtime effect). It declares
+     *     that the rendered value may be `null` (e.g. when delegating through a HasOne
+     *     that may be missing). Use this when you want the key to always be present
+     *     but the value to be nullable in the schema.
+     *   - `required: false` affects both runtime and OpenAPI. At runtime, when the
+     *     resolved value is `undefined` (which includes the case of a missing delegated
+     *     association with no `default`), the key is omitted from the rendered output.
+     *     In OpenAPI, the field is marked as not required.
+     *
      * @param targetName - The property name containing the target object (e.g., an association name)
      * @param name - The attribute name within the target object
      * @param options - Configuration options:
@@ -35,16 +48,22 @@ export default class DreamSerializerBuilder {
      *     (e.g., delegating `'user', 'email'` with `as: 'userEmail'` outputs the value
      *     under `userEmail`)
      *   - `default` - Value to use when the target object or its attribute is null/undefined
+     *     (not available when delegating to a `'type'` STI discriminator column: substituting
+     *     a discriminator string when the association is actually missing produces a response
+     *     indistinguishable from "association present with that type," which is misleading)
      *   - `openapi` - OpenAPI schema definition; required for non-Dream targets and json/jsonb
      *     columns, optional for standard Dream columns (where types are inferred)
-     *   - `optional` - Set to `true` to indicate the value can be null in the OpenAPI schema
-     *     (wraps the type in `anyOf: [schema, { type: 'null' }]`). For Dream models, this is
-     *     auto-inferred from optional BelongsTo associations. Use this when delegating through
-     *     a HasOne or other nullable association.
+     *   - `optional` - Set to `true` to mark the value as nullable in the OpenAPI schema
+     *     (wraps the type in `anyOf: [schema, { type: 'null' }]`). OpenAPI-only — the
+     *     key is still rendered (as `null`). For Dream models, this is auto-inferred
+     *     from optional BelongsTo associations. Use this when delegating through a
+     *     HasOne or other nullable association.
      *   - `precision` - Round decimal values to the specified number of decimal places (0–9)
-     *     during rendering; does not affect the OpenAPI shape
-     *   - `required` - Set to `false` to mark the attribute as optional in the OpenAPI schema;
-     *     when omitted, attributes are required by default
+     *     during rendering; does not affect the OpenAPI shape (not available when delegating
+     *     to a `'type'` STI discriminator column, which is always a string enum)
+     *   - `required` - Set to `false` to omit the key from the rendered output when the
+     *     resolved value is `undefined` (including a missing delegated association with
+     *     no `default`), and to mark the field as not required in the OpenAPI schema
      * @returns The serializer builder for method chaining
      *
      * @example

package/dist/esm/src/serializer/builders/ObjectSerializerBuilder.js

@@ -69,8 +69,20 @@ export default class ObjectSerializerBuilder {
      * Includes an attribute from a nested object in the serialized output.
      *
      * Accesses `targetName.name` on the data object. The `openapi` option is always
-     * required. If the target object or the delegated attribute is null/undefined,
-     * the `default` option value will be used if provided.
+     * required. When the target object or the delegated attribute is null/undefined,
+     * the resolution order is:
+     *   1. `default` if provided → renders the default value
+     *   2. `required: false` → omits the key entirely from the rendered output
+     *   3. otherwise → renders `null`
+     *
+     * `optional` and `required` are not aliases — they encode different things and can
+     * be used together:
+     *   - `optional: true` is an OpenAPI-only marker (no runtime effect). It declares
+     *     that the rendered value may be `null`. Use this when you want the key to always
+     *     be present but the value to be nullable in the schema.
+     *   - `required: false` affects both runtime and OpenAPI. At runtime, when the
+     *     resolved value is `undefined`, the key is omitted from the rendered output.
+     *     In OpenAPI, the field is marked as not required.
      *
      * @param targetName - The property name containing the target object
      * @param name - The attribute name within the target object
@@ -80,10 +92,14 @@ export default class ObjectSerializerBuilder {
      *     (e.g., delegating `'profile', 'avatarUrl'` with `as: 'avatar'` outputs the value
      *     under `avatar`)
      *   - `default` - Value to use when the target object or its attribute is null/undefined
+     *   - `optional` - Set to `true` to mark the value as nullable in the OpenAPI schema
+     *     (wraps the type in `anyOf: [schema, { type: 'null' }]`). OpenAPI-only — the
+     *     key is still rendered (as `null`)
      *   - `precision` - Round decimal values to the specified number of decimal places (0–9)
      *     during rendering; does not affect the OpenAPI shape
-     *   - `required` - Set to `false` to mark the attribute as optional in the OpenAPI schema;
-     *     when omitted, attributes are required by default
+     *   - `required` - Set to `false` to omit the key from the rendered output when the
+     *     resolved value is `undefined`, and to mark the field as not required in the
+     *     OpenAPI schema
      * @returns The serializer builder for method chaining
      *
      * @example

package/dist/types/src/cli/index.d.ts

@@ -1,7 +1,18 @@
-import { SpawnOptions } from 'child_process';
+import { SpawnOptions as NodeSpawnOptions } from 'child_process';
 import { Command } from 'commander';
 import DreamApp, { DreamAppInitOptions } from '../dream-app/index.js';
 import DreamCliLogger from './logger/DreamCliLogger.js';
+export type SpawnOptions = Omit<NodeSpawnOptions, 'shell'> & {
+    onStdout?: (str: string) => void;
+    /**
+     * Argv elements passed to the child as separate arguments. Defaults to `[]`.
+     * Each entry is passed literally — shell meta-characters (`$`, backticks,
+     * `&&`, spaces, etc.) inside any element are not interpreted by a shell.
+     * This is the right shape for any caller that interpolates a path or
+     * credential.
+     */
+    args?: string[];
+};
 export declare const CLI_INDENT = "                  ";
 export declare const baseColumnsWithTypesDescription = "space separated snake-case (except for belongs_to model name) properties like this:\n                      title:citext subtitle:string body_markdown:text style:enum:post_styles:formal,informal User:belongs_to\n                  \n                  all properties default to not nullable; null can be allowed by appending ':optional':\n                      subtitle:string:optional\n                  \n                  supported types:\n                      - uuid:\n                      - uuid[]:\n                          a column optimized for storing UUIDs\n                  \n                      - citext:\n                      - citext[]:\n                          case insensitive text (indexes and queries are automatically case insensitive)\n                  \n                      - encrypted:\n                          encrypted text (used in conjunction with the @deco.Encrypted decorator)\n                  \n                      - string:\n                      - string[]:\n                          varchar; allowed length defaults to 255, but may be customized, e.g.: subtitle:string:128 or subtitle:string:128:optional\n                  \n                      - text\n                      - text[]\n                      - date\n                      - date[]\n                      - datetime\n                      - datetime[]\n                      - time\n                      - time[]\n                      - timetz\n                      - timetz[]\n                      - integer\n                      - integer[]\n                  \n                      - decimal:\n                      - decimal[]:\n                          precision,scale is required, e.g.: volume:decimal:3,2 or volume:decimal:3,2:optional\n                  \n                          leveraging arrays, add the \"[]\" suffix, e.g.: volume:decimal[]:3,2\n                  \n                      - enum:\n                      - enum[]:\n                          include the enum name to automatically create the enum:\n                            type:enum:room_types:bathroom,kitchen,bedroom or type:enum:room_types:bathroom,kitchen,bedroom:optional\n                  \n                          omit the enum values to leverage an existing enum (omits the enum type creation):\n                            type:enum:room_types or type:enum:room_types:optional\n                  \n                          leveraging arrays, add the \"[]\" suffix, e.g.: type:enum[]:room_types:bathroom,kitchen,bedroom";
 export default class DreamCLI {
@@ -56,9 +67,51 @@ export default class DreamCLI {
         seedDb: () => Promise<void> | void;
         onSync: () => Promise<void> | void;
     }): void;
-    static spawn(command: string, opts?: SpawnOptions & {
-        onStdout?: (str: string) => void;
-    }): Promise<unknown>;
+    /**
+     * Run a developer-authored CLI command. Always runs in argv form (the
+     * underlying child_process `spawn` is called with `shell: false`):
+     * `command` is exec'd literally and `opts.args` are passed as separate
+     * argv elements. Shell-form invocation is intentionally not supported —
+     * there is no caller that needs `&&`-chaining, globs, or other shell
+     * features that can't be expressed as argv.
+     *
+     * For backward compatibility, `command` may contain implicit args
+     * separated by whitespace (e.g. `'pnpm psy sync'`); the leading token
+     * becomes the program and the rest are split out and prepended to any
+     * `opts.args` so the original argument order is preserved:
+     *
+     *     DreamCLI.spawn('pnpm psy sync')
+     *       → spawn('pnpm', ['psy', 'sync'])
+     *
+     *     DreamCLI.spawn('pnpm psy', { args: ['sync', '--flag'] })
+     *       → spawn('pnpm', ['psy', 'sync', '--flag'])
+     *
+     * ## Threat model (R-015)
+     *
+     * For dev-time CLI glue only (scaffolding, doc generation, type sync).
+     * **No runtime HTTP request input ever reaches this function.** Inputs
+     * are constant literals or composed from developer-supplied config
+     * (package.json scripts, CLI argv, scaffold templates) — never from
+     * runtime request input or any other untrusted external source.
+     *
+     * Argv-form is the safe choice for any caller that interpolates a
+     * config value, path, or credential: a database password containing
+     * `$` or backticks is passed literally to the child rather than
+     * interpreted by a shell.
+     *
+     * ## Layered defense
+     *
+     * Primary gate: every caller restricts spawn use to dev/test code paths
+     * (CLI commands, the dev watcher, scaffold-time code generators,
+     * generated `cli:sync` initializers wrapped in
+     * `if (AppEnv.isDevelopmentOrTest)`).
+     *
+     * Backstop: throws `SspawnRequiresDevelopmentOrTest` when `NODE_ENV` is
+     * anything other than `development` or `test`. Checking
+     * `!isDevelopmentOrTest` (rather than `isProduction`) means staging-style
+     * envs and any unforeseen NODE_ENV value also fail closed.
+     */
+    static spawn(command: string, opts?: SpawnOptions): Promise<void>;
     static get logger(): DreamCliLogger;
     private static _logger;
 }

package/dist/types/src/decorators/class/ReplicaSafe.d.ts

@@ -1 +1,2 @@
-export default function ReplicaSafe(): ClassDecorator;
+import Dream from '../../Dream.js';
+export default function ReplicaSafe(): (target: typeof Dream) => void;

package/dist/types/src/decorators/class/STI.d.ts

@@ -1,3 +1,3 @@
 import Dream from '../../Dream.js';
 export declare const STI_SCOPE_NAME = "dream:STI";
-export default function STI(dreamClass: typeof Dream): ClassDecorator;
+export default function STI(dreamClass: typeof Dream): (stiChildClass: typeof Dream) => void;

package/dist/types/src/decorators/class/SoftDelete.d.ts

@@ -1,3 +1,4 @@
+import Dream from '../../Dream.js';
 export declare const SOFT_DELETE_SCOPE_NAME = "dream:SoftDelete";
 /**
  * Instructs the model to set a timestamp when deleting,
@@ -34,4 +35,4 @@ export declare const SOFT_DELETE_SCOPE_NAME = "dream:SoftDelete";
  *   }
  * }
  */
-export default function SoftDelete(): ClassDecorator;
+export default function SoftDelete(): (target: typeof Dream) => void;

package/dist/types/src/dream/QueryDriver/Kysely.d.ts

@@ -1,5 +1,7 @@
+import type { ConnectionOptions as TlsConnectionOptions } from 'node:tls';
 import { DeleteQueryBuilder, Kysely, Transaction as KyselyTransaction, OrderByItemBuilder, SelectQueryBuilder, UpdateQueryBuilder } from 'kysely';
 import { DialectProviderCb } from '../../db/DreamDbConnection.js';
+import { SingleDbCredential } from '../../dream-app/index.js';
 import Dream from '../../Dream.js';
 import { SchemaBuilderInformationSchemaRow } from '../../helpers/cli/ASTBuilder.js';
 import { AssociationStatement } from '../../types/associations/shared.js';
@@ -467,3 +469,18 @@ export default class KyselyQueryDriver<DreamInstance extends Dream> extends Quer
     private applyOnePreload;
     private _applyOnePreload;
 }
+/**
+ * Resolve the value passed to `pg.Pool`'s `ssl` field for a given credential.
+ *
+ * Precedence:
+ *   1. If `connectionConf.ssl` is set (boolean or `tls.ConnectionOptions`),
+ *      pass it straight through to `pg`. This is the verified-TLS path —
+ *      apps configure `{ rejectUnauthorized: true, ca: <bundle> }` for
+ *      authenticated TLS against a private PKI, or `true` to use Node's
+ *      default verification against the system CA store.
+ *   2. Else if `connectionConf.useSsl` is `true`, fall back to
+ *      `{ rejectUnauthorized: false }` — encrypted but **not** authenticated.
+ *      Preserved for back-compat; new code should set `ssl` explicitly.
+ *   3. Else disable TLS.
+ */
+export declare function resolvePostgresSsl(connectionConf: SingleDbCredential): boolean | TlsConnectionOptions;

package/dist/types/src/dream-app/index.d.ts

@@ -1,4 +1,5 @@
 import { CompiledQuery } from 'kysely';
+import type { ConnectionOptions as TlsConnectionOptions } from 'node:tls';
 import { Context } from 'node:vm';
 import Dream from '../Dream.js';
 import QueryDriverBase from '../dream/QueryDriver/Base.js';
@@ -209,7 +210,30 @@ export interface SingleDbCredential {
     host: string;
     name: string;
     port: number;
-    useSsl: boolean;
+    /**
+     * @deprecated Use `ssl` instead.
+     *
+     * The legacy boolean opt-in for Postgres TLS. When `true` (and `ssl` is not
+     * set), Dream connects with `{ rejectUnauthorized: false }` — TLS is on but
+     * the server certificate is not verified. The new `ssl` field accepts a
+     * full `tls.ConnectionOptions` object so callers can opt into verified TLS
+     * (`ssl: { rejectUnauthorized: true, ca: readFileSync('ca.pem') }`) or use
+     * Node's defaults (`ssl: true`). This field is preserved for back-compat
+     * and will be removed in a future major version.
+     */
+    useSsl?: boolean;
+    /**
+     * Optional explicit TLS configuration passed straight through to `pg.Pool`'s
+     * `ssl` field. Takes precedence over the deprecated `useSsl` when provided.
+     *
+     * - `true` lets `pg` use Node's defaults (verified TLS against the system CA).
+     * - `false` disables TLS.
+     * - An object is `tls.ConnectionOptions` — set `rejectUnauthorized: true` plus
+     *   a `ca` bundle for verified TLS against a private PKI; set
+     *   `rejectUnauthorized: false` only if you accept opportunistic-TLS-without-
+     *   authentication (the historical default produced by `useSsl: true` alone).
+     */
+    ssl?: boolean | TlsConnectionOptions;
 }
 export type DreamLogger = {
     info: (...args: any[]) => void;

package/dist/types/src/encrypt/algorithms/aes-gcm/decryptAESGCM.d.ts

@@ -1,2 +1,2 @@
 import { EncryptAESAlgorithm } from '../../index.js';
-export default function decryptAESGCM<RetType>(algorithm: EncryptAESAlgorithm, encrypted: string, key: string): RetType | null;
+export default function decryptAESGCM<RetType>(algorithm: EncryptAESAlgorithm, encrypted: string, key: string): RetType;

package/dist/types/src/encrypt/index.d.ts

@@ -1,7 +1,66 @@
 export default class Encrypt {
     static encrypt(data: any, { algorithm, key }: EncryptOptions): string;
+    /**
+     * Decrypts a value previously produced by {@link Encrypt.encrypt}.
+     *
+     * Behavior depends on whether `legacyOpts` is provided:
+     *
+     * **Two-arg form** (no rotation):
+     * - `null`/`undefined` input returns `null`.
+     * - Cipher op / auth tag / payload-shape failure throws `DecryptionError`.
+     * - Successful decrypt with non-JSON plaintext throws `DecryptionParseError`.
+     *
+     * **Three-arg form** (rotation): tries the current key first; on
+     * `DecryptionError` falls back to the legacy key. If both fail, throws
+     * `DecryptionWithRotationError` carrying both per-key errors. A
+     * `DecryptionParseError` from the current key is **not** retried — the
+     * cipher already matched, so a parse failure means the encrypted format
+     * is wrong (an app bug), not a wrong key.
+     *
+     * `MissingEncryptionKey` propagates from either form when a key is missing.
+     *
+     * @throws MissingEncryptionKey
+     * @throws DecryptionError
+     * @throws DecryptionParseError
+     * @throws DecryptionWithRotationError
+     */
     static decrypt<RetType>(encrypted: string, { algorithm, key }: DecryptOptions, legacyOpts?: DecryptOptions): RetType | null;
     private static attemptDecryptionWithLegacyKeys;
+    /**
+     * Generates a base64-encoded random key suitable for the given algorithm.
+     *
+     * ## Rotation workflow
+     *
+     * 1. Generate a new key: `const newKey = Encrypt.generateKey('aes-256-gcm')`.
+     * 2. Configure rotation by setting both `current` and `legacy`. For
+     *    encrypted columns: `dreamApp.set('encryption', { columns: { current:
+     *    { algorithm: 'aes-256-gcm', key: newKey }, legacy: { algorithm:
+     *    'aes-256-gcm', key: oldKey } } })`. For cookies, use the equivalent
+     *    shape under `psychicApp.set('encryption', { cookies: { current,
+     *    legacy } })`.
+     * 3. Deploy. New encryptions use `current`; existing ciphertext continues
+     *    to decrypt via `legacy` fallback.
+     * 4. For cookies, wait at least the cookie `maxAge` so all in-flight
+     *    cookies have either expired or been re-issued under the new key. For
+     *    `@Encrypted` columns, re-encrypt every existing row under the new
+     *    key (read each row and write it back; the setter re-encrypts with
+     *    `current`).
+     * 5. Drop `legacy` from config and deploy again.
+     *
+     * ## When to rotate
+     *
+     * - On a scheduled cadence (90–180 days is a reasonable policy default).
+     * - Incident response: leaked env file, departing employee with key
+     *   access, or any suspected key compromise.
+     *
+     * ## How long to keep `legacy`
+     *
+     * - For cookies: at least the cookie `maxAge`, so in-flight sessions are
+     *   not forced to re-authenticate.
+     * - For `@Encrypted` columns: until every existing row has been
+     *   re-encrypted under the new key. Dropping `legacy` early will cause
+     *   `DecryptionWithRotationError` on any not-yet-rewritten row.
+     */
     static generateKey(algorithm: EncryptAlgorithm): string;
     static validateKey(base64EncodedKey: string, algorithm: EncryptAlgorithm): boolean;
 }

package/dist/types/src/errors/SspawnRequiresDevelopmentOrTest.d.ts

@@ -0,0 +1,5 @@
+export default class SspawnRequiresDevelopmentOrTest extends Error {
+    private command;
+    constructor(command: string);
+    get message(): string;
+}

package/dist/types/src/errors/encrypt/DecryptionError.d.ts

@@ -0,0 +1,3 @@
+export default class DecryptionError extends Error {
+    get message(): string;
+}

package/dist/types/src/errors/encrypt/DecryptionParseError.d.ts

@@ -0,0 +1,3 @@
+export default class DecryptionParseError extends Error {
+    get message(): string;
+}

package/dist/types/src/errors/encrypt/DecryptionWithRotationError.d.ts

@@ -0,0 +1,7 @@
+import DecryptionError from './DecryptionError.js';
+export default class DecryptionWithRotationError extends Error {
+    readonly currentKeyError: DecryptionError;
+    readonly legacyKeyError: DecryptionError;
+    constructor(currentKeyError: DecryptionError, legacyKeyError: DecryptionError);
+    get message(): string;
+}

package/dist/types/src/ops/index.d.ts

@@ -56,17 +56,38 @@ declare const ops: {
      * Creates an `OpsStatement` using the SQL `LIKE` operator for case-sensitive pattern matching.
      * Use `%` as a wildcard in the pattern string.
      *
+     * **User-supplied patterns:** the value is bound as a parameter (no SQL
+     * injection), but `%`, `_`, and `\` in the bound value are still interpreted
+     * as wildcards by the SQL engine. Wrap user input with `ops.like.escape`
+     * if you need literal matching:
+     *
+     *     User.where({ name: ops.like(`%${ops.like.escape(query)}%`) })
+     *
+     * `ops.like.escape` escapes the three metacharacters that PostgreSQL's
+     * `LIKE` / `ILIKE` operators treat as wildcards (`\`, `%`, `_`) so the
+     * returned string matches literally. The same helper applies to all four
+     * LIKE-family ops (`like`, `ilike`, `not.like`, `not.ilike`); it is exposed
+     * here as the canonical entry point. If a caller uses `ESCAPE '...'` with
+     * a non-default character this helper will not be appropriate.
+     *
      * @param like - The pattern string (e.g. `'%hello%'`).
      * @returns An `OpsStatement` using the `like` operator.
      *
      * @example
      * User.where({ name: ops.like('%alice%') })
      */
-    like: (like: string) => OpsStatement<"like", string, undefined>;
+    like: ((like: string) => OpsStatement<"like", string, undefined>) & {
+        escape: (input: string) => string;
+    };
     /**
      * Creates an `OpsStatement` using the SQL `ILIKE` operator for case-insensitive pattern matching.
      * Use `%` as a wildcard in the pattern string.
      *
+     * **User-supplied patterns:** the value is bound as a parameter (no SQL
+     * injection), but `%`, `_`, and `\` in the bound value are still interpreted
+     * as wildcards by the SQL engine. Wrap user input with `ops.like.escape`
+     * if you need literal matching.
+     *
      * @param ilike - The pattern string (e.g. `'%hello%'`).
      * @returns An `OpsStatement` using the `ilike` operator.
      *
@@ -208,6 +229,9 @@ declare const ops: {
         /**
          * Creates an `OpsStatement` using the `NOT LIKE` operator for case-sensitive pattern exclusion.
          *
+         * **User-supplied patterns:** see the note on `ops.like`. Wrap user input
+         * with `ops.like.escape` for literal matching.
+         *
          * @param like - The pattern string (e.g. `'%spam%'`).
          * @returns An `OpsStatement` using the `not like` operator.
          *
@@ -218,6 +242,9 @@ declare const ops: {
         /**
          * Creates an `OpsStatement` using the `NOT ILIKE` operator for case-insensitive pattern exclusion.
          *
+         * **User-supplied patterns:** see the note on `ops.ilike`. Wrap user input
+         * with `ops.like.escape` for literal matching.
+         *
          * @param ilike - The pattern string (e.g. `'%spam%'`).
          * @returns An `OpsStatement` using the `not ilike` operator.
          *

package/dist/types/src/serializer/builders/DreamSerializerBuilder.d.ts

@@ -59,14 +59,27 @@ export default class DreamSerializerBuilder<DataTypeForOpenapi extends typeof Dr
     /**
      * Includes an attribute from a nested object in the serialized output.
      *
-     * Accesses `targetName.name` on the data object. If the target object
-     * or the delegated attribute is null/undefined, the `default` option value
-     * will be used if provided.
+     * Accesses `targetName.name` on the data object. When the target object or the
+     * delegated attribute is null/undefined, the resolution order is:
+     *   1. `default` if provided → renders the default value
+     *   2. `required: false` → omits the key entirely from the rendered output
+     *   3. otherwise → renders `null`
      *
      * When the target is a Dream model, OpenAPI types may be automatically inferred
      * for standard database columns. For json/jsonb columns or non-Dream targets,
      * the `openapi` option is required.
      *
+     * `optional` and `required` are not aliases — they encode different things and can
+     * be used together:
+     *   - `optional: true` is an OpenAPI-only marker (no runtime effect). It declares
+     *     that the rendered value may be `null` (e.g. when delegating through a HasOne
+     *     that may be missing). Use this when you want the key to always be present
+     *     but the value to be nullable in the schema.
+     *   - `required: false` affects both runtime and OpenAPI. At runtime, when the
+     *     resolved value is `undefined` (which includes the case of a missing delegated
+     *     association with no `default`), the key is omitted from the rendered output.
+     *     In OpenAPI, the field is marked as not required.
+     *
      * @param targetName - The property name containing the target object (e.g., an association name)
      * @param name - The attribute name within the target object
      * @param options - Configuration options:
@@ -74,16 +87,22 @@ export default class DreamSerializerBuilder<DataTypeForOpenapi extends typeof Dr
      *     (e.g., delegating `'user', 'email'` with `as: 'userEmail'` outputs the value
      *     under `userEmail`)
      *   - `default` - Value to use when the target object or its attribute is null/undefined
+     *     (not available when delegating to a `'type'` STI discriminator column: substituting
+     *     a discriminator string when the association is actually missing produces a response
+     *     indistinguishable from "association present with that type," which is misleading)
      *   - `openapi` - OpenAPI schema definition; required for non-Dream targets and json/jsonb
      *     columns, optional for standard Dream columns (where types are inferred)
-     *   - `optional` - Set to `true` to indicate the value can be null in the OpenAPI schema
-     *     (wraps the type in `anyOf: [schema, { type: 'null' }]`). For Dream models, this is
-     *     auto-inferred from optional BelongsTo associations. Use this when delegating through
-     *     a HasOne or other nullable association.
+     *   - `optional` - Set to `true` to mark the value as nullable in the OpenAPI schema
+     *     (wraps the type in `anyOf: [schema, { type: 'null' }]`). OpenAPI-only — the
+     *     key is still rendered (as `null`). For Dream models, this is auto-inferred
+     *     from optional BelongsTo associations. Use this when delegating through a
+     *     HasOne or other nullable association.
      *   - `precision` - Round decimal values to the specified number of decimal places (0–9)
-     *     during rendering; does not affect the OpenAPI shape
-     *   - `required` - Set to `false` to mark the attribute as optional in the OpenAPI schema;
-     *     when omitted, attributes are required by default
+     *     during rendering; does not affect the OpenAPI shape (not available when delegating
+     *     to a `'type'` STI discriminator column, which is always a string enum)
+     *   - `required` - Set to `false` to omit the key from the rendered output when the
+     *     resolved value is `undefined` (including a missing delegated association with
+     *     no `default`), and to mark the field as not required in the OpenAPI schema
      * @returns The serializer builder for method chaining
      *
      * @example
@@ -106,9 +125,18 @@ export default class DreamSerializerBuilder<DataTypeForOpenapi extends typeof Dr
      */
     delegatedAttribute<ProvidedModelType = undefined, ProvidedTargetName extends ProvidedModelType extends undefined ? undefined : Exclude<keyof ProvidedModelType, DreamPropertiesToExclude> = ProvidedModelType extends undefined ? undefined : Exclude<keyof ProvidedModelType, DreamPropertiesToExclude>, ActualDataType extends ProvidedModelType extends undefined ? InstanceType<DataTypeForOpenapi> : ProvidedModelType = ProvidedModelType extends undefined ? InstanceType<DataTypeForOpenapi> : ProvidedModelType, TargetName extends ProvidedTargetName extends undefined ? Exclude<keyof ActualDataType, DreamPropertiesToExclude> : ProvidedTargetName & keyof ActualDataType = ProvidedTargetName extends undefined ? Exclude<keyof ActualDataType, DreamPropertiesToExclude> : ProvidedTargetName & keyof ActualDataType, AssociatedModelType = Exclude<ActualDataType[TargetName], null>, TargetAttributeName extends AssociatedModelType extends object ? Exclude<keyof AssociatedModelType, DreamPropertiesToExclude> & string : never = AssociatedModelType extends object ? Exclude<keyof AssociatedModelType, DreamPropertiesToExclude> & string : never>(targetName: TargetName, name: TargetAttributeName, options?: AssociatedModelType extends Dream ? TargetAttributeName extends NonJsonDreamColumnNames<AssociatedModelType> & keyof AssociatedModelType & 'type' ? AutomaticSerializerAttributeOptionsForType & {
         optional?: boolean;
-    } : TargetAttributeName extends DreamVirtualColumns<AssociatedModelType>[number] ? SerializerAttributeOptionsForVirtualColumn : TargetAttributeName extends NonJsonDreamColumnNames<AssociatedModelType> & keyof AssociatedModelType & string ? (AutomaticSerializerAttributeOptions & {
+        required?: false;
+    } : TargetAttributeName extends DreamVirtualColumns<AssociatedModelType>[number] ? SerializerAttributeOptionsForVirtualColumn & {
+        optional?: boolean;
+    } : TargetAttributeName extends NonJsonDreamColumnNames<AssociatedModelType> & keyof AssociatedModelType & string ? (AutomaticSerializerAttributeOptions & {
         optional?: boolean;
-    }) | NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption : NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption : NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption): this;
+    }) | (NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption & {
+        optional?: boolean;
+    }) : NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption & {
+        optional?: boolean;
+    } : NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption & {
+        optional?: boolean;
+    }): this;
     /**
      * Includes a computed value in the serialized output.
      *

package/dist/types/src/serializer/builders/ObjectSerializerBuilder.d.ts

@@ -63,8 +63,20 @@ export default class ObjectSerializerBuilder<MaybeNullDataType extends object |
      * Includes an attribute from a nested object in the serialized output.
      *
      * Accesses `targetName.name` on the data object. The `openapi` option is always
-     * required. If the target object or the delegated attribute is null/undefined,
-     * the `default` option value will be used if provided.
+     * required. When the target object or the delegated attribute is null/undefined,
+     * the resolution order is:
+     *   1. `default` if provided → renders the default value
+     *   2. `required: false` → omits the key entirely from the rendered output
+     *   3. otherwise → renders `null`
+     *
+     * `optional` and `required` are not aliases — they encode different things and can
+     * be used together:
+     *   - `optional: true` is an OpenAPI-only marker (no runtime effect). It declares
+     *     that the rendered value may be `null`. Use this when you want the key to always
+     *     be present but the value to be nullable in the schema.
+     *   - `required: false` affects both runtime and OpenAPI. At runtime, when the
+     *     resolved value is `undefined`, the key is omitted from the rendered output.
+     *     In OpenAPI, the field is marked as not required.
      *
      * @param targetName - The property name containing the target object
      * @param name - The attribute name within the target object
@@ -74,10 +86,14 @@ export default class ObjectSerializerBuilder<MaybeNullDataType extends object |
      *     (e.g., delegating `'profile', 'avatarUrl'` with `as: 'avatar'` outputs the value
      *     under `avatar`)
      *   - `default` - Value to use when the target object or its attribute is null/undefined
+     *   - `optional` - Set to `true` to mark the value as nullable in the OpenAPI schema
+     *     (wraps the type in `anyOf: [schema, { type: 'null' }]`). OpenAPI-only — the
+     *     key is still rendered (as `null`)
      *   - `precision` - Round decimal values to the specified number of decimal places (0–9)
      *     during rendering; does not affect the OpenAPI shape
-     *   - `required` - Set to `false` to mark the attribute as optional in the OpenAPI schema;
-     *     when omitted, attributes are required by default
+     *   - `required` - Set to `false` to omit the key from the rendered output when the
+     *     resolved value is `undefined`, and to mark the field as not required in the
+     *     OpenAPI schema
      * @returns The serializer builder for method chaining
      *
      * @example
@@ -100,7 +116,9 @@ export default class ObjectSerializerBuilder<MaybeNullDataType extends object |
      * })
      * ```
      */
-    delegatedAttribute<ProvidedModelType = undefined, ProvidedAttributeName extends ProvidedModelType extends undefined ? undefined : Exclude<keyof ProvidedModelType, DreamPropertiesToExclude> = ProvidedModelType extends undefined ? undefined : Exclude<keyof ProvidedModelType, DreamPropertiesToExclude>, ActualDataType extends ProvidedModelType extends undefined ? DataType : ProvidedModelType = ProvidedModelType extends undefined ? DataType : ProvidedModelType, TargetName extends ProvidedAttributeName extends undefined ? Exclude<keyof ActualDataType, DreamPropertiesToExclude> : ProvidedAttributeName & keyof ActualDataType = ProvidedAttributeName extends undefined ? Exclude<keyof ActualDataType, DreamPropertiesToExclude> : ProvidedAttributeName & keyof ActualDataType, TargetObject extends ActualDataType[TargetName] = ActualDataType[TargetName], AttributeName extends TargetObject extends object ? Exclude<keyof TargetObject, DreamPropertiesToExclude> & string : never = TargetObject extends object ? Exclude<keyof TargetObject, DreamPropertiesToExclude> & string : never>(targetName: TargetName, name: AttributeName, options: NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption): this;
+    delegatedAttribute<ProvidedModelType = undefined, ProvidedAttributeName extends ProvidedModelType extends undefined ? undefined : Exclude<keyof ProvidedModelType, DreamPropertiesToExclude> = ProvidedModelType extends undefined ? undefined : Exclude<keyof ProvidedModelType, DreamPropertiesToExclude>, ActualDataType extends ProvidedModelType extends undefined ? DataType : ProvidedModelType = ProvidedModelType extends undefined ? DataType : ProvidedModelType, TargetName extends ProvidedAttributeName extends undefined ? Exclude<keyof ActualDataType, DreamPropertiesToExclude> : ProvidedAttributeName & keyof ActualDataType = ProvidedAttributeName extends undefined ? Exclude<keyof ActualDataType, DreamPropertiesToExclude> : ProvidedAttributeName & keyof ActualDataType, TargetObject extends ActualDataType[TargetName] = ActualDataType[TargetName], AttributeName extends TargetObject extends object ? Exclude<keyof TargetObject, DreamPropertiesToExclude> & string : never = TargetObject extends object ? Exclude<keyof TargetObject, DreamPropertiesToExclude> & string : never>(targetName: TargetName, name: AttributeName, options: NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption & {
+        optional?: boolean;
+    }): this;
     /**
      * Includes a computed value in the serialized output.
      *