@rvoh/dream 2.5.7 → 2.6.0

package/dist/types/src/decorators/Decorators.d.ts

@@ -56,6 +56,10 @@ export default class Decorators<TD extends typeof Dream, T extends Dream = Insta
      * @returns A Scope decorator
      */
     Scope(this: Decorators<TD>, opts?: {
+        /**
+         * If `true`, this scope will be applied automatically to all queries involving this model.
+         * Defaults to `false`.
+         */
         default?: boolean;
     }): any;
     /**
@@ -116,10 +120,14 @@ export default class Decorators<TD extends typeof Dream, T extends Dream = Insta
      * @returns A Validates decorator
      */
     Validates<VT extends ValidationType, VTArgs extends VT extends 'numericality' ? {
+        /** The minimum allowed value (inclusive). */
         min?: number;
+        /** The maximum allowed value (inclusive). */
         max?: number;
     } : VT extends 'length' ? {
+        /** The minimum allowed length (inclusive). */
         min: number;
+        /** The maximum allowed length (inclusive). */
         max?: number;
     } : VT extends 'contains' ? string | RegExp : never>(this: Decorators<TD>, type: VT, args?: VTArgs): any;
     /**

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

@@ -1,5 +1,3 @@
 import Dream from '../../Dream.js';
 export declare const STI_SCOPE_NAME = "dream:STI";
-export default function STI(dreamClass: typeof Dream, { value }?: {
-    value?: string;
-}): ClassDecorator;
+export default function STI(dreamClass: typeof Dream): ClassDecorator;

package/dist/types/src/decorators/field/sortable/Sortable.d.ts

@@ -1,5 +1,14 @@
 export default function Sortable(opts?: SortableOpts): any;
 interface SortableOpts {
+    /**
+     * A column name or array of column names that define the scope within which
+     * position values are unique. Records are sorted independently within each scope.
+     *
+     * ```ts
+     * @deco.Sortable({ scope: 'species' })
+     * public positionWithinSpecies: number
+     * ```
+     */
     scope?: string | string[];
 }
 export interface SortableFieldConfig {

package/dist/types/src/decorators/field/validation/Validates.d.ts

@@ -1,10 +1,14 @@
 import Dream from '../../../Dream.js';
 import { ValidationType } from '../../../types/validation.js';
 export default function Validates<VT extends ValidationType, VTArgs extends VT extends 'numericality' ? {
+    /** The minimum allowed value (inclusive). */
     min?: number;
+    /** The maximum allowed value (inclusive). */
     max?: number;
 } : VT extends 'length' ? {
+    /** The minimum allowed length (inclusive). */
     min: number;
+    /** The maximum allowed length (inclusive). */
     max?: number;
 } : VT extends 'contains' ? string | RegExp : never>(type: VT, args?: VTArgs): any;
 export declare function validatesImplementation<VT extends ValidationType, VTArgs extends VT extends 'numericality' ? {

package/dist/types/src/decorators/static-method/Scope.d.ts

@@ -1,5 +1,9 @@
 import Dream from '../../Dream.js';
 export default function Scope(opts?: {
+    /**
+     * If `true`, this scope will be applied automatically to all queries involving this model.
+     * Defaults to `false`.
+     */
     default?: boolean;
 }): any;
 export declare function scopeImplementation(t: typeof Dream, key: string, opts?: {

package/dist/types/src/dream/LeftJoinLoadBuilder.d.ts

@@ -8,13 +8,16 @@ export default class LeftJoinLoadBuilder<DreamInstance extends Dream> {
     private dream;
     private query;
     /**
-     * An intermediate class on the way to executing a load
-     * query. this can be accessed on an instance of a dream
-     * model by using the `#load` method:
+     * An intermediate builder for loading associations onto a Dream model
+     * via a single left-join SQL query. Accessed via `#leftJoinLoad`.
+     *
+     * **Note:** The LeftJoinLoadBuilder works on a clone of the original model.
+     * Call `.execute()` to get the clone with associations loaded.
      *
      * ```ts
      * const user = await User.firstOrFail()
-     * await user.load('settings').execute()
+     * const loaded = await user.leftJoinLoad('settings').execute()
+     * loaded.settings // association is loaded on the returned clone
      * ```
      */
     constructor(dream: Dream, dreamTransaction?: (DreamTransaction<any> | null) | undefined);
@@ -32,17 +35,20 @@ export default class LeftJoinLoadBuilder<DreamInstance extends Dream> {
      */
     leftJoinLoad<I extends LeftJoinLoadBuilder<DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], const Arr extends readonly unknown[], const LastArg extends VariadicLeftJoinLoadArgs<DreamInstance, DB, Schema, TableName, Arr>>(this: I, ...args: [...Arr, LastArg]): I;
     /**
-     * executes a load builder query, binding
-     * all associations to their respective model
-     * instances.
+     * Executes the left-join load query, returning a **clone** of the original model
+     * with all requested associations loaded. The original instance is not modified.
      *
      * ```ts
      * const user = await User.firstOrFail()
-     * await user
-     *   .load('settings')
-     *   .load('posts', 'comments', 'replies', ['image', 'localizedText'])
+     * const loaded = await user
+     *   .leftJoinLoad('settings')
+     *   .leftJoinLoad('posts', 'comments', 'replies')
      *   .execute()
+     *
+     * loaded.settings // works — associations are on the returned clone
      * ```
+     *
+     * @returns A clone of the Dream instance with all requested associations loaded
      */
     execute(): Promise<DreamInstance>;
     private associationToPreloadedDreamsAndWhatTheyPointTo;

package/dist/types/src/dream/LoadBuilder.d.ts

@@ -1,6 +1,7 @@
 import Dream from '../Dream.js';
 import { PassthroughOnClause } from '../types/associations/shared.js';
-import { DreamSerializerKey, PassthroughColumnNames } from '../types/dream.js';
+import { DbConnectionType } from '../types/db.js';
+import { AllDefaultScopeNames, DreamSerializerKey, PassthroughColumnNames } from '../types/dream.js';
 import { LoadForModifierFn } from '../types/query.js';
 import { VariadicLoadArgs } from '../types/variadic.js';
 import DreamTransaction from './DreamTransaction.js';
@@ -9,17 +10,66 @@ export default class LoadBuilder<DreamInstance extends Dream> {
     private dream;
     private query;
     /**
-     * An intermediate class on the way to executing a load
-     * query. this can be accessed on an instance of a dream
-     * model by using the `#load` method:
+     * An intermediate builder for loading associations onto a Dream model.
+     * Accessed via the `#load` method on a Dream instance.
+     *
+     * **Note:** The LoadBuilder works on a clone of the original model.
+     * Call `.execute()` to get the clone with associations loaded.
      *
      * ```ts
      * const user = await User.firstOrFail()
-     * await user.load('settings').execute()
+     * const loaded = await user.load('settings').execute()
+     * loaded.settings // association is loaded on the returned clone
      * ```
      */
     constructor(dream: Dream, dreamTransaction?: (DreamTransaction<any> | null) | undefined);
     passthrough<I extends LoadBuilder<DreamInstance>, PassthroughColumns extends PassthroughColumnNames<DreamInstance>>(this: I, passthroughWhereStatement: PassthroughOnClause<PassthroughColumns>): I;
+    /**
+     * Prevents a specific default scope from applying when
+     * loading associations
+     *
+     * ```ts
+     * const user = await User.firstOrFail()
+     * const loaded = await user
+     *   .load('posts')
+     *   .removeDefaultScope('dream:SoftDelete')
+     *   .execute()
+     * ```
+     *
+     * @param scopeName - The default scope to bypass
+     * @returns The LoadBuilder instance for chaining
+     */
+    removeDefaultScope<I extends LoadBuilder<DreamInstance>>(this: I, scopeName: AllDefaultScopeNames<DreamInstance>): I;
+    /**
+     * Prevents all default scopes from applying when
+     * loading associations
+     *
+     * ```ts
+     * const user = await User.firstOrFail()
+     * const loaded = await user
+     *   .load('posts')
+     *   .removeAllDefaultScopes()
+     *   .execute()
+     * ```
+     *
+     * @returns The LoadBuilder instance for chaining
+     */
+    removeAllDefaultScopes<I extends LoadBuilder<DreamInstance>>(this: I): I;
+    /**
+     * Sets the database connection to use when loading associations
+     *
+     * ```ts
+     * const user = await User.firstOrFail()
+     * const loaded = await user
+     *   .load('posts')
+     *   .connection('replica')
+     *   .execute()
+     * ```
+     *
+     * @param connection - The connection type ('primary' or 'replica')
+     * @returns The LoadBuilder instance for chaining
+     */
+    connection<I extends LoadBuilder<DreamInstance>>(this: I, connection: DbConnectionType): I;
     /**
      * Attaches a load statement to the load builder
      *
@@ -82,19 +132,22 @@ export default class LoadBuilder<DreamInstance extends Dream> {
      */
     loadFor<I extends LoadBuilder<DreamInstance>, SerializerKey extends DreamSerializerKey<DreamInstance>>(this: I, serializerKey: SerializerKey, modifierFn?: LoadForModifierFn): I;
     /**
-     * Executes a load builder query, binding
-     * all associations to their respective model
-     * instances.
+     * Executes the load query, binding all associations to a **clone** of the
+     * original model instance. The original instance is not modified.
+     *
+     * You must use the returned value to access the loaded associations:
      *
      * ```ts
      * const user = await User.firstOrFail()
-     * await user
+     * const loaded = await user
      *   .load('settings')
      *   .load('posts', 'comments', 'replies', ['image', 'localizedText'])
      *   .execute()
+     *
+     * loaded.settings // works — associations are on the returned clone
      * ```
      *
-     * @returns The Dream instance with all associations loaded
+     * @returns A clone of the Dream instance with all requested associations loaded
      */
     execute(): Promise<DreamInstance>;
 }

package/dist/types/src/dream/Query.d.ts

@@ -1146,7 +1146,7 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * Updates all records matching the Query
      *
      * ```ts
-     * await User.where({ email: ops.ilike('%burpcollaborator%') }).updateAll({ email: null })
+     * await User.where({ email: ops.ilike('%burpcollaborator%') }).update({ email: null })
      * // 12
      * ```
      * @param attributes - The attributes used to update the records

package/dist/types/src/dream/constants.d.ts

@@ -1,5 +1,7 @@
 export declare const primaryKeyTypes: readonly ["uuid7", "uuid4", "bigserial", "bigint", "integer"];
 export declare const TRIGRAM_OPERATORS: readonly ["%", "<%", "<<%"];
+export declare const RECURSIVE_SERIALIZATION_MAX_REPEATS = 4;
+export declare const RECURSIVE_DESTROY_PRELOAD_MAX_REPEATS = 4;
 declare class RequiredAttribute {
     constructor();
 }

package/dist/types/src/dream/internal/buildAssociationPaths.d.ts

@@ -0,0 +1,12 @@
+import { DreamClassAndAssociationNameTuple } from '../../types/recursiveSerialization.js';
+export interface AssociationPathEdge<NodeType> {
+    nextNode: NodeType | null;
+    tuple: DreamClassAndAssociationNameTuple;
+}
+export default function buildAssociationPaths<NodeType>(rootNode: NodeType, opts: BuildAssociationPathsOptions<NodeType>): DreamClassAndAssociationNameTuple[][];
+type BuildAssociationPathsOptions<NodeType> = {
+    getKey: (node: NodeType) => string;
+    getEdges: (node: NodeType) => AssociationPathEdge<NodeType>[];
+    maxRepeats: number;
+};
+export {};

package/dist/types/src/dream/internal/buildDependentDestroyPreloadPaths.d.ts

@@ -0,0 +1,17 @@
+import Dream from '../../Dream.js';
+import { DreamClassAndAssociationNameTuple } from '../../types/recursiveSerialization.js';
+/**
+ * @internal
+ *
+ * Recursively walks `dependent: 'destroy'` associations starting from the given
+ * Dream class, producing an array of preload paths. Each path is an array of
+ * [DreamClass, associationName] tuples representing a chain from root to leaf.
+ *
+ * Allows the same Dream class to appear up to MAX_REPEATS times in a single
+ * path to support tree structures (e.g. a Category with `dependent: 'destroy'`
+ * on its children, which are also Categories).
+ *
+ * Used to build a preload tree so that all records in the cascade can be loaded
+ * upfront, eliminating N+1 queries during destroy.
+ */
+export default function buildDependentDestroyPreloadPaths(dreamClass: typeof Dream): DreamClassAndAssociationNameTuple[][];

package/dist/types/src/dream/internal/buildSerializerPreloadPaths.d.ts

@@ -0,0 +1,3 @@
+import Dream from '../../Dream.js';
+import { DreamClassAndAssociationNameTuple } from '../../types/recursiveSerialization.js';
+export default function buildSerializerPreloadPaths(dreamClass: typeof Dream, serializerKey?: string): DreamClassAndAssociationNameTuple[][];

package/dist/types/src/dream/internal/convertDreamClassAndAssociationNameTupleArrayToPreloadArgs.d.ts

@@ -1,5 +1,5 @@
 import { LoadForModifierFn } from '../../types/query.js';
-import { DreamClassAndAssociationNameTuple } from './extractNestedPaths.js';
+import { DreamClassAndAssociationNameTuple } from '../../types/recursiveSerialization.js';
 export default function convertDreamClassAndAssociationNameTupleArrayToPreloadArgs(dreamClassAndAssociationNameTupleArray: DreamClassAndAssociationNameTuple[], modifierFn?: LoadForModifierFn, counter?: {
     count: number;
 }): (string | {

package/dist/types/src/dream/internal/destroyAssociatedRecords.d.ts

@@ -5,6 +5,10 @@ import { ReallyDestroyOptions } from './destroyDream.js';
  * @internal
  *
  * Destroys all HasOne/HasMany associations on this
- * dream that are marked as `dependent: 'destroy'`
+ * dream that are marked as `dependent: 'destroy'`.
+ *
+ * Expects associations to be preloaded onto the dream instance
+ * via `loadDependentDestroyTree`. Iterates loaded associations
+ * directly instead of querying the database.
  */
 export default function destroyAssociatedRecords<I extends Dream>(dream: I, txn: DreamTransaction<I>, options: ReallyDestroyOptions<I>): Promise<void>;

package/dist/types/src/dream/internal/loadDependentDestroyTree.d.ts

@@ -0,0 +1,17 @@
+import Dream from '../../Dream.js';
+import { AllDefaultScopeNames } from '../../types/dream.js';
+import DreamTransaction from '../DreamTransaction.js';
+/**
+ * @internal
+ *
+ * Loads all `dependent: 'destroy'` associations onto the dream instance
+ * upfront, eliminating N+1 queries during cascade destruction.
+ *
+ * Returns a clone of the dream with all associations loaded.
+ * If there are no dependent-destroy associations, returns the original dream.
+ */
+export default function loadDependentDestroyTree<I extends Dream>(dream: I, txn: DreamTransaction<I>, { reallyDestroy, bypassAllDefaultScopes, defaultScopesToBypass, }: {
+    reallyDestroy: boolean;
+    bypassAllDefaultScopes: boolean;
+    defaultScopesToBypass: AllDefaultScopeNames<I>[];
+}): Promise<I>;

package/dist/types/src/dream/internal/resolveSerializerAssociationEdges.d.ts

@@ -0,0 +1,13 @@
+import Dream from '../../Dream.js';
+import { DreamModelSerializerType, SimpleObjectSerializerType } from '../../types/serializer.js';
+export interface ResolvedSerializerAssociationEdge {
+    associationAs: string;
+    sourceDreamClass: typeof Dream;
+    type: 'rendersOne' | 'rendersMany' | 'delegatedAttribute';
+    serializerAssociationName: string;
+    targets: {
+        dreamClass: typeof Dream;
+        serializer: DreamModelSerializerType | SimpleObjectSerializerType;
+    }[];
+}
+export default function resolveSerializerAssociationEdges(dreamClass: typeof Dream, serializer: DreamModelSerializerType | SimpleObjectSerializerType): ResolvedSerializerAssociationEdge[];