@guren/orm 2.7.1 → 2.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/dist/index.d.ts +74 -16
  2. package/dist/index.js +618 -326
  3. package/package.json +1 -1
package/dist/index.d.ts CHANGED
@@ -17,18 +17,25 @@ declare function applyAccessors<T extends PlainObject>(record: T, accessors?: Ac
17
17
  /** Apply mutators to data before persistence, returning a new object. */
18
18
  declare function applyMutators(data: PlainObject, mutators?: MutatorDefinitions): PlainObject;
19
19
  //#endregion
20
- //#region src/QueryBuilder.d.ts
21
- type FieldKey<TRecord extends PlainObject> = keyof TRecord & string;
20
+ //#region src/internal-keys.d.ts
22
21
  /**
23
- * Key for the prepared-payload update terminal. Exported for `Model` across
24
- * the module boundary, but kept out of the package entry point.
22
+ * What `Model`, `QueryBuilder` and the adapters share without importing each
23
+ * other, kept out of the package entry point. The keys live here rather than on
24
+ * either class because `Model` names one as a computed static key: evaluated
25
+ * while the two modules' import cycle is still unwinding, a key declared in the
26
+ * other one is in its temporal dead zone.
25
27
  */
28
+ /** Bulk update with an already-filtered, already-prepared payload. */
26
29
  declare const PREPARED_UPDATE: unique symbol;
27
- /**
28
- * Key for the global-scope seal. Exported for `Model` across the module
29
- * boundary, but kept out of the package entry point.
30
- */
30
+ /** Freezes the conditions applied so far as the model's global scopes. */
31
31
  declare const SEAL_SCOPES: unique symbol;
32
+ /** The model's one read-transform pass over a result set. */
33
+ declare const READ_TRANSFORMS: unique symbol;
34
+ /** Rows as the adapter read them, for the joins a relation loader makes. */
35
+ declare const RAW_RESULTS: unique symbol;
36
+ //#endregion
37
+ //#region src/QueryBuilder.d.ts
38
+ type FieldKey<TRecord extends PlainObject> = keyof TRecord & string;
32
39
  type WhereOperator = '=' | '!=' | '>' | '<' | '>=' | '<=' | 'like' | 'in' | 'not in' | 'is null' | 'is not null';
33
40
  interface SimpleCondition {
34
41
  type: 'simple';
@@ -114,6 +121,11 @@ declare class QueryBuilder<TRecord extends PlainObject = PlainObject, TResult ex
114
121
  orderBy(field: FieldKey<TRecord>, direction?: OrderDirection): this;
115
122
  limit(n: number): this;
116
123
  offset(n: number): this;
124
+ /**
125
+ * Narrows the row to these columns. The model's accessors are then skipped:
126
+ * one reading a column `fields` left out would fabricate a value from
127
+ * `undefined`. Casts still apply to the columns that are there.
128
+ */
117
129
  select<TKey extends FieldKey<TRecord>>(...fields: readonly TKey[]): QueryBuilder<TRecord, Pick<TRecord, TKey>>;
118
130
  /** Apply a named query scope defined on the model. */
119
131
  scope(name: string): this;
@@ -122,14 +134,30 @@ declare class QueryBuilder<TRecord extends PlainObject = PlainObject, TResult ex
122
134
  * callbacks, each run after the foreign-key filter on exactly the level its key
123
135
  * names. Pitfalls: a top-level `orWhere()` ORs against the foreign-key filter
124
136
  * (group it); `select()` must keep the relation's key column or the relation is
125
- * empty; `limit()` applies to the one batched query, not per parent record.
137
+ * empty; `limit()` caps the whole result set, not each parent's share.
126
138
  */
127
139
  with(...relations: (string | Record<string, EagerLoadConstraint>)[]): this;
128
140
  get(): Promise<TResult[]>;
141
+ /**
142
+ * Runs the query and hands back the rows as the adapter read them. Symbol-keyed
143
+ * and never re-exported: a named public method here would be a supported way to
144
+ * read past a model's casts.
145
+ */
146
+ [RAW_RESULTS](): Promise<TResult[]>;
147
+ /** The one read pipeline: rows, then eager loads, then the model's transforms. */
148
+ private fetch;
149
+ private fetchRaw;
129
150
  first(): Promise<TResult | null>;
130
151
  /** @throws ModelNotFoundException (404) if no record matches. */
131
152
  firstOrFail(): Promise<TResult>;
132
153
  count(): Promise<number>;
154
+ /**
155
+ * @internal Row count per distinct value of `field`, as one grouped COUNT
156
+ * where the adapter issues it. Without `countByAdvanced` the rows are loaded
157
+ * and counted here, narrowed to that one column where the adapter can project
158
+ * and whole where it cannot.
159
+ */
160
+ countBy(field: FieldKey<TRecord>): Promise<Map<unknown, number>>;
133
161
  /**
134
162
  * Takes positional arguments or the same options object as
135
163
  * `Model.paginate()`, so the two APIs stay interchangeable.
@@ -212,6 +240,17 @@ interface ORMAdapterAdvanced extends ORMAdapter {
212
240
  select?: readonly string[];
213
241
  }, queryOptions?: AdapterQueryOptions): Promise<TRecord[]>;
214
242
  countAdvanced?<TRecord extends PlainObject = PlainObject>(table: unknown, conditions: WhereCondition[], queryOptions?: AdapterQueryOptions): Promise<number>;
243
+ /**
244
+ * Keys the adapter admits in one IN list, from the bound-variable limit the
245
+ * driver it holds sets. Without it, the ORM uses the figure every dialect it
246
+ * supports admits.
247
+ */
248
+ maxInListSize?(): number;
249
+ /** `SELECT field, COUNT(*) ... GROUP BY field` under `conditions`. */
250
+ countByAdvanced?(table: unknown, field: string, conditions: WhereCondition[], queryOptions?: AdapterQueryOptions): Promise<Array<{
251
+ key: unknown;
252
+ count: number;
253
+ }>>;
215
254
  updateAdvanced?<TRecord extends PlainObject = PlainObject>(table: unknown, conditions: WhereCondition[], data: PlainObject, writeOptions?: AdapterQueryOptions): Promise<TRecord>;
216
255
  deleteAdvanced?<TRecord extends PlainObject = PlainObject>(table: unknown, conditions: WhereCondition[], writeOptions?: AdapterQueryOptions): Promise<number | PlainObject | void>;
217
256
  }
@@ -442,8 +481,15 @@ declare abstract class Model<TRecord extends PlainObject = PlainObject> {
442
481
  static serialize<T extends typeof Model>(this: T, record: TRecordFor<T>): PlainObject;
443
482
  static serializeMany<T extends typeof Model>(this: T, records: TRecordFor<T>[]): PlainObject[];
444
483
  static applyCasts<T extends PlainObject>(record: T): T;
445
- /** Read-time transforms, in order: casts then accessors. */
484
+ /** The one read-transform pass for a record, in order: casts then accessors. */
446
485
  protected static applyReadTransforms<T extends PlainObject>(record: T): T;
486
+ /**
487
+ * The same pass over a result set. Symbol-keyed for `QueryBuilder` across the
488
+ * module boundary, and kept out of the package entry point. `projected` marks
489
+ * a row `select()` narrowed: an accessor there would read columns that are not
490
+ * on it, while `applyCasts` already skips an absent one.
491
+ */
492
+ static [READ_TRANSFORMS]<T extends PlainObject>(records: T[], projected?: boolean): T[];
447
493
  /**
448
494
  * In order: `deniedFields()` throws, checked on the raw input so no later
449
495
  * rule can swallow them; `id` is stripped silently; then, with `fillable`
@@ -458,6 +504,11 @@ declare abstract class Model<TRecord extends PlainObject = PlainObject> {
458
504
  static getRelationDefinition(name: string): RelationDefinition | undefined;
459
505
  static resolveTable(): unknown;
460
506
  static all<T extends typeof Model>(this: T, queryOptions?: ModelQueryOptions): Promise<Array<TRecordFor<T>>>;
507
+ /**
508
+ * The rows a relation load joins against, as the adapter read them: a cast on
509
+ * the parent's key column would stop the child rows from matching it.
510
+ */
511
+ protected static rawRecords<T extends typeof Model>(this: T, where: WhereClauseFor<T> | undefined, queryOptions?: ModelQueryOptions): Promise<Array<TRecordFor<T>>>;
461
512
  static find<T extends typeof Model>(this: T, id: TRecordFor<T>[keyof TRecordFor<T> & string], key?: keyof TRecordFor<T> & string, queryOptions?: ModelQueryOptions): Promise<TRecordFor<T> | null>;
462
513
  /** @throws ModelNotFoundException (404) when no record matches. */
463
514
  static findOrFail<T extends typeof Model>(this: T, id: TRecordFor<T>[keyof TRecordFor<T> & string], key?: keyof TRecordFor<T> & string, queryOptions?: ModelQueryOptions): Promise<TRecordFor<T>>;
@@ -551,6 +602,12 @@ declare abstract class Model<TRecord extends PlainObject = PlainObject> {
551
602
  * await User.paginate({ page: 2, perPage: 20, where: { status: 'active' } })
552
603
  */
553
604
  static paginate<T extends typeof Model>(this: T, options?: PaginateOptions<TRecordFor<T>>, queryOptions?: ModelQueryOptions): Promise<PaginatedResult<TRecordFor<T>>>;
605
+ /**
606
+ * The builder owns pagination: the count matters as much as the rows, and a
607
+ * second sanitise-count-slice here would agree with the builder's by
608
+ * inspection rather than by construction.
609
+ */
610
+ private static paginationQuery;
554
611
  static withPaginate<T extends typeof Model, K extends RelationPath<T>>(this: T, relations: K | readonly K[], options?: PaginateOptions<TRecordFor<T>>, queryOptions?: ModelQueryOptions): Promise<PaginatedResult<TRecordFor<T> & RelationTypePick<T, K | readonly K[]>>>;
555
612
  static create<T extends typeof Model>(this: T, data: TCreateFor<T>, writeOptions?: ModelWriteOptions): Promise<TRecordFor<T>>;
556
613
  /**
@@ -610,12 +667,12 @@ declare abstract class Model<TRecord extends PlainObject = PlainObject> {
610
667
  * leaf looks itself up under that whole key, not under `comments`.
611
668
  */
612
669
  protected static loadRelationLevel<T extends typeof Model>(this: T, records: Array<PlainObject>, head: string, tails: readonly string[], queryOptions?: ModelQueryOptions, constraints?: EagerLoadConstraints, pathPrefix?: string): Promise<void>;
613
- protected static loadHasMany(records: Array<PlainObject>, definition: HasManyRelationDefinition, queryOptions?: ModelQueryOptions, constraint?: EagerLoadConstraint): Promise<void>;
614
- protected static loadHasOne(records: Array<PlainObject>, definition: HasOneRelationDefinition, queryOptions?: ModelQueryOptions, constraint?: EagerLoadConstraint): Promise<void>;
615
- protected static loadBelongsTo(records: Array<PlainObject>, definition: BelongsToRelationDefinition, queryOptions?: ModelQueryOptions, constraint?: EagerLoadConstraint): Promise<void>;
616
- protected static loadBelongsToMany(records: Array<PlainObject>, definition: BelongsToManyRelationDefinition, queryOptions?: ModelQueryOptions, constraint?: EagerLoadConstraint): Promise<void>;
617
- protected static loadHasManyThrough(records: Array<PlainObject>, definition: HasManyThroughRelationDefinition, queryOptions?: ModelQueryOptions, constraint?: EagerLoadConstraint): Promise<void>;
618
- protected static loadMorphMany(records: Array<PlainObject>, definition: MorphManyRelationDefinition, queryOptions?: ModelQueryOptions, constraint?: EagerLoadConstraint): Promise<void>;
670
+ protected static loadHasMany(records: Array<PlainObject>, definition: HasManyRelationDefinition, queryOptions?: ModelQueryOptions, constraint?: EagerLoadConstraint): Promise<boolean>;
671
+ protected static loadHasOne(records: Array<PlainObject>, definition: HasOneRelationDefinition, queryOptions?: ModelQueryOptions, constraint?: EagerLoadConstraint): Promise<boolean>;
672
+ protected static loadBelongsTo(records: Array<PlainObject>, definition: BelongsToRelationDefinition, queryOptions?: ModelQueryOptions, constraint?: EagerLoadConstraint): Promise<boolean>;
673
+ protected static loadBelongsToMany(records: Array<PlainObject>, definition: BelongsToManyRelationDefinition, queryOptions?: ModelQueryOptions, constraint?: EagerLoadConstraint): Promise<boolean>;
674
+ protected static loadHasManyThrough(records: Array<PlainObject>, definition: HasManyThroughRelationDefinition, queryOptions?: ModelQueryOptions, constraint?: EagerLoadConstraint): Promise<boolean>;
675
+ protected static loadMorphMany(records: Array<PlainObject>, definition: MorphManyRelationDefinition, queryOptions?: ModelQueryOptions, constraint?: EagerLoadConstraint): Promise<boolean>;
619
676
  protected static loadMorphTo(records: Array<PlainObject>, definition: MorphToRelationDefinition, queryOptions?: ModelQueryOptions, constraint?: EagerLoadConstraint): Promise<void>;
620
677
  }
621
678
  type TRecordFor<T extends typeof Model> = T extends {
@@ -833,6 +890,7 @@ type DrizzleLikeSelect = {
833
890
  orderBy?: (...clauses: unknown[]) => DrizzleLikeSelect;
834
891
  limit?: (value: number) => DrizzleLikeSelect;
835
892
  offset?: (value: number) => DrizzleLikeSelect;
893
+ groupBy?: (...columns: unknown[]) => DrizzleLikeSelect;
836
894
  all?: () => Promise<unknown[]>;
837
895
  get?: () => Promise<unknown>;
838
896
  };