@getstrata/core 2.2.50 → 2.2.52

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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,20 @@
1
1
  # @getstrata/core changelog
2
2
 
3
+ ## 2.2.52
4
+
5
+ - Attach eager relations to offset pages; apply to-many limits/offsets per owner with bounded window queries while retaining scopes and repository dispatch.
6
+ - Persist static-create observer edits while retaining resolved initial casts before observers; transform only changed fields again, preserving unchanged values, forced attributes and cancellation.
7
+ - Preserve immutable protected write-hook outputs by merging observer changes into framework-owned values rather than mutating extension-owned results.
8
+ - Fence invalidated array-cache fills and share one request correlation ID between context, logs and response middleware.
9
+ - Expose optional one-based job attempts and encode/hydrate failed-job JSON/timestamps at the repository storage boundary for durable cross-driver recovery.
10
+ - Hydrate only selected recovery columns so projection results retain their exact field shape.
11
+
12
+ ## 2.2.51
13
+
14
+ - Decode static URL pathnames exactly once while preserving generic filesystem path semantics, malformed/traversal rejection and literal percent/space names.
15
+ - Load explicit nested polymorphic paths using their concrete model and nested relation owners, batching by constructor identity while preserving flat eager records, flat lazy models, private state and visibility scopes.
16
+ - Preserve retrieved-observer invalidation/materialization and once-per-hydration callback getter dispatch; cache bookkeeping inspects only the existing observer list.
17
+
3
18
  ## 2.2.50
4
19
 
5
20
  - Align the lockstep version with the bootstrap HTTP-only drain-reporting correction. Core runtime, ORM, transaction, lifecycle coordinator and public/protected APIs are unchanged.
@@ -9,6 +9,7 @@ declare class SimpleCache {
9
9
  get<T>(key: string): T | undefined;
10
10
  set<T>(key: string, value: T, ttlMs?: number): void;
11
11
  getOrSet<T>(key: string, loader: () => Promise<T>, ttlMs?: number): Promise<T>;
12
+ getOrSetTagged<T>(key: string, loader: () => Promise<T>, tags: string[], ttlMs?: number): Promise<T>;
12
13
  attachTags(key: string, tags: string[]): void;
13
14
  flushTags(tags: string[]): number;
14
15
  invalidate(key: string): boolean;
@@ -6,6 +6,7 @@ declare class SimpleCacheStore implements CacheStore {
6
6
  get<T>(key: string): Promise<T | undefined>;
7
7
  set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
8
8
  getOrSet<T>(key: string, loader: () => Promise<T>, ttlMs?: number): Promise<T>;
9
+ getOrSetTagged<T>(key: string, loader: () => Promise<T>, tags: string[], ttlMs?: number): Promise<T>;
9
10
  attachTags(key: string, tags: string[]): Promise<void>;
10
11
  flushTags(tags: string[]): Promise<number>;
11
12
  invalidate(key: string): Promise<boolean>;
@@ -86,6 +86,7 @@ declare class BaseRepository<TEntity extends object, PrimaryKey extends keyof TE
86
86
  loadHasManyThroughForParents<TParent extends object, LocalKey extends keyof TParent & string, FirstKey extends string, SecondLocalKey extends string, SecondKey extends keyof TEntity & string>(parents: readonly TParent[], relation: HasManyThroughRelation<TParent, TEntity, LocalKey, FirstKey, SecondLocalKey, SecondKey>, options?: QueryOptions<TEntity>): Promise<Map<TParent[LocalKey], TEntity[]>>;
87
87
  loadBelongsToForParents<TChild extends object, TParent extends object, ForeignKey extends keyof TChild & string, OwnerKey extends keyof TParent & string>(children: readonly TChild[], relation: BelongsToRelation<TChild, TParent, ForeignKey, OwnerKey>, parentRepository: BaseRepository<TParent, OwnerKey>, options?: Omit<QueryOptions<TParent>, "where">): Promise<Map<TChild[ForeignKey], TParent>>;
88
88
  loadMorphManyForParents<TParent extends object, LocalKey extends keyof TParent & string, MorphTypeKey extends keyof TEntity & string, MorphIdKey extends keyof TEntity & string>(parents: readonly TParent[], relation: MorphManyRelation<TParent, TEntity, LocalKey, MorphTypeKey, MorphIdKey>, options?: Omit<QueryOptions<TEntity>, "where">): Promise<Map<TParent[LocalKey], TEntity[]>>;
89
+ private findRelationRows;
89
90
  loadMorphOneForParents<TParent extends object, LocalKey extends keyof TParent & string, MorphTypeKey extends keyof TEntity & string, MorphIdKey extends keyof TEntity & string>(parents: readonly TParent[], relation: MorphOneRelation<TParent, TEntity, LocalKey, MorphTypeKey, MorphIdKey>, options?: Omit<QueryOptions<TEntity>, "where">): Promise<Map<TParent[LocalKey], TEntity | undefined>>;
90
91
  loadMorphToForChildren<TChild extends object, TParent extends object, MorphTypeKey extends keyof TChild & string, MorphIdKey extends keyof TChild & string, OwnerKey extends keyof TParent & string>(children: readonly TChild[], relation: MorphToRelation<TChild, MorphTypeKey, MorphIdKey>, repositoriesByType: ReadonlyMap<string, BaseRepository<TParent, OwnerKey>>, options?: Omit<QueryOptions<TParent>, "where">): Promise<Map<TChild[MorphIdKey], TParent>>;
91
92
  loadBelongsToManyForParents<TParent extends object, TRelated extends object, Pivot extends object, ParentKey extends keyof TParent & string, RelatedKey extends keyof TRelated & string, ForeignPivotKey extends keyof Pivot & string, RelatedPivotKey extends keyof Pivot & string>(parents: readonly TParent[], relation: BelongsToManyRelation<TParent, TRelated, Pivot, ParentKey, RelatedKey, ForeignPivotKey, RelatedPivotKey>, relatedRepository: BaseRepository<TRelated, RelatedKey>, options?: Omit<QueryOptions<TRelated>, "where">): Promise<Map<TParent[ParentKey], TRelated[]>>;
@@ -27,6 +27,23 @@ declare function buildSelectQuery<TEntity extends object>(table: TableDefinition
27
27
  text: string;
28
28
  params: unknown[];
29
29
  };
30
+ declare const EAGER_ROW_NUMBER = "__strata_eager_row_number";
31
+ /** Database-side per-owner bounds; never fetch an unbounded batch to slice in JS. */
32
+ declare function buildLimitedRelationQuery<TEntity extends object>(table: TableDefinition<TEntity>, options: QueryOptions<TEntity>, partition: {
33
+ table: string;
34
+ column: string;
35
+ }, source: (columns: string, rank: string, params: unknown[]) => string): {
36
+ text: string;
37
+ params: unknown[];
38
+ };
39
+ declare function buildLimitedHasManyQuery<TEntity extends object>(table: TableDefinition<TEntity>, options: QueryOptions<TEntity>, partition: {
40
+ table: string;
41
+ column: string;
42
+ ownerAlias?: string;
43
+ }): {
44
+ text: string;
45
+ params: unknown[];
46
+ };
30
47
  declare function buildCountQuery<TEntity extends object>(table: TableDefinition<TEntity>, where?: QueryWhere<TEntity>, options?: Pick<QueryOptions<TEntity>, "withTrashed" | "onlyTrashed" | "joins" | "groupBy">, whereNodes?: readonly WhereNode<TEntity>[]): {
31
48
  text: string;
32
49
  params: unknown[];
@@ -78,4 +95,4 @@ declare function buildConditionalWriteQuery<TEntity extends object, PrimaryKey e
78
95
  text: string;
79
96
  params: unknown[];
80
97
  };
81
- export { assertSafeProjectionExpression, buildAdvancedWhereClause, buildConditionalWriteQuery, buildCountQuery, buildDeleteByIdQuery, buildGroupedCountQuery, buildGroupedSumQuery, buildIncrementQuery, buildInsertQuery, buildJoinClause, buildOrderByClause, buildProjectionQuery, buildQueryWhereClause, buildRestoreByIdQuery, buildSelectQuery, buildSoftDeleteByIdQuery, buildUpdateQuery, buildUpsertQuery, buildWhereClause, parseQualifiedColumn, qualifyColumn, quoteIdentifier, resolveQualifiedColumn, resolveSoftDeleteColumn, };
98
+ export { assertSafeProjectionExpression, buildAdvancedWhereClause, buildConditionalWriteQuery, buildCountQuery, buildDeleteByIdQuery, buildGroupedCountQuery, buildGroupedSumQuery, buildIncrementQuery, buildInsertQuery, buildJoinClause, buildLimitedHasManyQuery, buildLimitedRelationQuery, buildOrderByClause, buildProjectionQuery, buildQueryWhereClause, buildRestoreByIdQuery, buildSelectQuery, buildSoftDeleteByIdQuery, buildUpdateQuery, buildUpsertQuery, buildWhereClause, EAGER_ROW_NUMBER, parseQualifiedColumn, qualifyColumn, quoteIdentifier, resolveQualifiedColumn, resolveSoftDeleteColumn, };
@@ -179,7 +179,7 @@ declare class MorphToRelationQuery<TChild extends object, ChildKey extends keyof
179
179
  constructor(parent: RelationHost<TChild, ChildKey>, relatedByType: Record<string, RelatedModelClass<Record<string, unknown>, "id">>, relation: MorphToRelation<TChild, keyof TChild & string, keyof TChild & string>);
180
180
  where(where: QueryWhere<Record<string, unknown>>): this;
181
181
  applyEagerLoad(query: RepositoryQuery<TChild, ChildKey>, alias: string): void;
182
- hydrateEager(row: Record<string, unknown>, alias: string): unknown;
182
+ hydrateEager(row: Record<string, unknown>, alias: string, forNestedLoading?: boolean): unknown;
183
183
  toExistsClause(parentTable: string): ExistsClause;
184
184
  get(): Promise<RelatedRecord | null>;
185
185
  pluck(column: string): Promise<unknown[]>;
@@ -215,7 +215,7 @@ declare class HasManyThroughRelationQuery<TParent extends object, ParentKey exte
215
215
  type AnyRelationQuery = {
216
216
  kind: RelationKind;
217
217
  applyEagerLoad(query: unknown, alias: string): void;
218
- hydrateEager(row: Record<string, unknown>, alias: string): unknown;
218
+ hydrateEager(row: Record<string, unknown>, alias: string, forNestedLoading?: boolean): unknown;
219
219
  get(): Promise<unknown>;
220
220
  toExistsClause(parentTable: string): ExistsClause;
221
221
  where?(where: Record<string, unknown>): unknown;
@@ -4,6 +4,8 @@ type RequestMeta = {
4
4
  peerAddress?: string | null;
5
5
  userAgent: string | null;
6
6
  request?: Request;
7
+ /** Canonical correlation identity shared by response policies and logging. */
8
+ requestId?: string;
7
9
  /** Registered route template; never a URL supplied by the client. */
8
10
  routeTemplate?: string;
9
11
  /** API error contracts take precedence over client content negotiation. */
@@ -18,5 +20,6 @@ type RequestMeta = {
18
20
  declare const requestMetaContext: import("node:async_hooks").AsyncLocalStorage<RequestMeta>;
19
21
  declare function runWithRequestMeta<T>(meta: RequestMeta, callback: () => T | Promise<T>): T | Promise<T>;
20
22
  declare function currentRequestMeta(): RequestMeta;
23
+ declare function resolveRequestId(request: Request): string;
21
24
  export type { RequestMeta };
22
- export { currentRequestMeta, requestMetaContext, runWithRequestMeta };
25
+ export { currentRequestMeta, requestMetaContext, resolveRequestId, runWithRequestMeta };
@@ -1,7 +1,10 @@
1
1
  import { BaseRepository } from "@getstrata/core/database/baseRepository";
2
+ import type { MutationValues, QueryOptions } from "@getstrata/core/database/types";
2
3
  import type { FailedJobRecord } from "./types";
3
4
  declare class FailedJobRepository extends BaseRepository<FailedJobRecord, "id"> {
4
5
  constructor();
6
+ create(values: MutationValues<FailedJobRecord>): Promise<FailedJobRecord>;
7
+ findAll(options?: QueryOptions<FailedJobRecord>): Promise<FailedJobRecord[]>;
5
8
  }
6
9
  export { FailedJobRepository };
7
10
  export default FailedJobRepository;
@@ -1,6 +1,8 @@
1
1
  type QueuePriority = "high" | "default" | "low";
2
2
  /** Logical identity is stable across automatic recovery and supported manual replay. */
3
3
  interface JobContext {
4
+ /** One-based execution attempt supplied by the framework retry owner. */
5
+ readonly attempt?: number;
4
6
  readonly jobId: string;
5
7
  readonly signal: AbortSignal;
6
8
  readonly deadlineAtMs?: number;
@@ -8,7 +8,7 @@ interface QueueJobEnvelope {
8
8
  cancellable?: boolean;
9
9
  }
10
10
  declare function parseQueueJobEnvelope(rawPayload: string): QueueJobEnvelope | null;
11
- declare function runQueueJob(envelope: QueueJobEnvelope, failedJobs: FailedJobService, options?: {
11
+ declare function runQueueJob(envelope: QueueJobEnvelope, failedJobs: Pick<FailedJobService, "recordFailure">, options?: {
12
12
  onFailureRecorded?: () => void;
13
13
  context?: import("./index").JobContext;
14
14
  deferRetry?: (envelope: QueueJobEnvelope, delayMs: number) => Promise<void>;
@@ -1,4 +1,4 @@
1
1
  declare function assertPathUnderRoot(rootDirectory: string, userPath: string): string;
2
- /** Map a URL pathname onto a document root. Leading slashes are not filesystem-absolute. */
2
+ /** Decode a URL pathname once; leading slashes are not filesystem-absolute. */
3
3
  declare function assertUrlPathUnderRoot(rootDirectory: string, urlPathname: string): string;
4
4
  export { assertPathUnderRoot, assertUrlPathUnderRoot };
@@ -1560,6 +1560,42 @@ function buildSelectQuery(table, options = {}, whereNodes = []) {
1560
1560
  params
1561
1561
  };
1562
1562
  }
1563
+ var EAGER_ROW_NUMBER = "__strata_eager_row_number";
1564
+ function buildLimitedRelationQuery(table, options, partition, source) {
1565
+ if (options.lock || options.groupBy?.length || options.having) {
1566
+ throw new Error("Limited eager relations do not support row locks, grouping or HAVING.");
1567
+ }
1568
+ if (table.columns.includes(EAGER_ROW_NUMBER) || options.select?.some((item) => ("as" in item) && item.as === EAGER_ROW_NUMBER)) {
1569
+ throw new Error(`Reserved eager relation column: ${EAGER_ROW_NUMBER}`);
1570
+ }
1571
+ buildLimitClause(options.limit);
1572
+ buildOffsetClause(options.offset);
1573
+ if (!Number.isSafeInteger((options.offset ?? 0) + (options.limit ?? 0))) {
1574
+ throw new Error("Limited eager relation bounds must fit a safe integer.");
1575
+ }
1576
+ const order = [...normalizeOrderBy(options.orderBy ?? table.defaultOrderBy)];
1577
+ if (!order.some((item) => item.column === table.primaryKey || item.column === `${table.name}.${table.primaryKey}`)) {
1578
+ order.push({ column: table.primaryKey, direction: "ASC" });
1579
+ }
1580
+ const ordering = buildOrderByClause(table.name, order);
1581
+ const params = [];
1582
+ const columns = buildSelectList(table, options.select, params);
1583
+ const rank = `ROW_NUMBER() OVER (PARTITION BY ${qualifyColumn(partition.table, partition.column)}${ordering}) AS ${quoteIdentifier(EAGER_ROW_NUMBER)}`;
1584
+ const sql = source(columns, rank, params);
1585
+ const offset = options.offset ?? 0;
1586
+ const upper = options.limit === undefined ? "" : ` AND ${quoteIdentifier(EAGER_ROW_NUMBER)} <= ${offset + options.limit}`;
1587
+ return {
1588
+ text: `SELECT * FROM (${sql}) AS ${quoteIdentifier("__strata_eager")} WHERE ${quoteIdentifier(EAGER_ROW_NUMBER)} > ${offset}${upper} ORDER BY ${quoteIdentifier(EAGER_ROW_NUMBER)}`,
1589
+ params
1590
+ };
1591
+ }
1592
+ function buildLimitedHasManyQuery(table, options, partition) {
1593
+ return buildLimitedRelationQuery(table, options, partition, (columns, rank, params) => {
1594
+ const { clause } = buildQueryWhereClause(table, options, options.whereNodes, params);
1595
+ const owner = partition.ownerAlias ? `, ${qualifyColumn(partition.table, partition.column)} AS ${quoteIdentifier(partition.ownerAlias)}` : "";
1596
+ return `SELECT ${columns}${owner}, ${rank} FROM ${quoteIdentifier(table.name)}${buildJoinClause(options.joins)}${clause}`;
1597
+ });
1598
+ }
1563
1599
  function buildCountQuery(table, where = {}, options = {}, whereNodes = []) {
1564
1600
  const params = [];
1565
1601
  const { clause, params: whereParams } = buildQueryWhereClause(table, {
@@ -1795,6 +1831,17 @@ function buildThroughWhere(table, options, parentIds) {
1795
1831
  function buildHasManyThroughQuery(table, relation, parentIds, options) {
1796
1832
  const throughParentKey = relation.throughParentKey ?? "__through_parent_id";
1797
1833
  const farTable = table.name;
1834
+ if (options.limit !== undefined || options.offset !== undefined) {
1835
+ return buildLimitedRelationQuery(table, options, { table: relation.throughTable, column: relation.firstKey }, (columns, rank, params) => {
1836
+ const placeholders = parentIds.map((id) => {
1837
+ params.push(id);
1838
+ return currentSqlDialect().placeholder(params.length);
1839
+ }).join(", ");
1840
+ const { clause } = buildQueryWhereClause(table, options, options.whereNodes, params);
1841
+ const extra = clause ? ` AND (${clause.replace(/^ WHERE /, "")})` : "";
1842
+ return `SELECT ${columns}, ${qualifyColumn(relation.throughTable, relation.firstKey)} AS ${quoteIdentifier(throughParentKey)}, ${rank} FROM ${quoteIdentifier(farTable)} INNER JOIN ${quoteIdentifier(relation.throughTable)} ON ${qualifyColumn(relation.throughTable, relation.secondLocalKey)} = ${qualifyColumn(farTable, relation.secondKey)}${buildJoinClause(options.joins)} WHERE ${qualifyColumn(relation.throughTable, relation.firstKey)} IN (${placeholders})${extra}`;
1843
+ });
1844
+ }
1798
1845
  const columns = table.columns.map((column) => `${qualifyColumn(farTable, column)}`).join(", ");
1799
1846
  const placeholders = parentIds.map((_, index) => currentSqlDialect().placeholder(index + 1)).join(", ");
1800
1847
  const { text: extraWhere, params: extraParams } = buildThroughWhere(table, options, parentIds);
@@ -2381,11 +2428,12 @@ class RepositoryQuery {
2381
2428
  return await this.attach(rows);
2382
2429
  }
2383
2430
  async paginate(options) {
2384
- return await this.repository.paginate({
2431
+ const page = await this.repository.paginate({
2385
2432
  ...this.buildOptions(),
2386
2433
  page: options.page,
2387
2434
  perPage: options.perPage
2388
2435
  });
2436
+ return { ...page, data: await this.attach(page.data) };
2389
2437
  }
2390
2438
  async chunk(count, callback) {
2391
2439
  await this.repository.chunk(count, async (rows) => callback(await this.attach(rows)), this.buildOptions());
@@ -2554,6 +2602,7 @@ function readOrder(order) {
2554
2602
  ...order.nulls === undefined ? {} : { nulls: order.nulls }
2555
2603
  };
2556
2604
  }
2605
+ var RELATION_WINDOW = Symbol("relationWindow");
2557
2606
 
2558
2607
  class BaseRepository {
2559
2608
  table;
@@ -2610,9 +2659,17 @@ class BaseRepository {
2610
2659
  if (options.lock && (!hasActiveTransaction() || this.connection !== repositoryConnection && !isActiveTransactionConnection(this.connection))) {
2611
2660
  throw new Error("Row locks require the framework active transaction connection.");
2612
2661
  }
2613
- const { whereNodes, ...queryOptions } = options;
2614
- const { text, params } = buildSelectQuery(this.table, queryOptions, whereNodes ?? []);
2615
- return await this.connection.unsafe(text, params);
2662
+ const {
2663
+ whereNodes,
2664
+ [RELATION_WINDOW]: window,
2665
+ ...queryOptions
2666
+ } = options;
2667
+ const { text, params } = window ? buildLimitedHasManyQuery(this.table, { ...queryOptions, whereNodes }, window) : buildSelectQuery(this.table, queryOptions, whereNodes ?? []);
2668
+ const rows = await this.connection.unsafe(text, params);
2669
+ if (window)
2670
+ for (const row of rows)
2671
+ delete row[EAGER_ROW_NUMBER];
2672
+ return rows;
2616
2673
  });
2617
2674
  }
2618
2675
  async paginate(options) {
@@ -3098,9 +3155,8 @@ class BaseRepository {
3098
3155
  return indexHasManyRelation(parents, [], relation);
3099
3156
  }
3100
3157
  const parentIds = [...new Set(parents.map((parent) => parent[relation.localKey]))];
3101
- const children = await this.findWhere({
3102
- [relation.foreignKey]: parentIds
3103
- }, options);
3158
+ const where = { [relation.foreignKey]: parentIds };
3159
+ const children = await this.findRelationRows(where, options, relation.foreignKey);
3104
3160
  return indexHasManyRelation(parents, children, relation);
3105
3161
  }
3106
3162
  async findHasManyThrough(parentId, relation, options = {}) {
@@ -3117,6 +3173,8 @@ class BaseRepository {
3117
3173
  const parentIds = [...new Set(parents.map((parent) => parent[relation.localKey]))];
3118
3174
  const { text, params } = buildHasManyThroughQuery(this.table, relation, parentIds, options);
3119
3175
  const children = await this.connection.unsafe(text, params);
3176
+ for (const child of children)
3177
+ delete child[EAGER_ROW_NUMBER];
3120
3178
  return indexHasManyThroughRelation(parents, children, relation);
3121
3179
  }
3122
3180
  async loadBelongsToForParents(children, relation, parentRepository, options = {}) {
@@ -3134,12 +3192,21 @@ class BaseRepository {
3134
3192
  return indexMorphManyRelation(parents, [], relation);
3135
3193
  }
3136
3194
  const parentIds = [...new Set(parents.map((parent) => parent[relation.localKey]))];
3137
- const children = await this.findWhere({
3195
+ const children = await this.findRelationRows({
3138
3196
  [relation.morphTypeKey]: relation.morphType,
3139
3197
  [relation.morphIdKey]: parentIds
3140
- }, options);
3198
+ }, options, relation.morphIdKey);
3141
3199
  return indexMorphManyRelation(parents, children, relation);
3142
3200
  }
3201
+ async findRelationRows(where, options, foreignKey) {
3202
+ if (options.limit === undefined && options.offset === undefined)
3203
+ return this.findWhere(where, options);
3204
+ const bounded = {
3205
+ ...options,
3206
+ [RELATION_WINDOW]: { table: this.table.name, column: foreignKey }
3207
+ };
3208
+ return this.findWhere(where, bounded);
3209
+ }
3143
3210
  async loadMorphOneForParents(parents, relation, options = {}) {
3144
3211
  const grouped = await this.loadMorphManyForParents(parents, relation, options);
3145
3212
  const result = new Map;
@@ -3192,9 +3259,53 @@ class BaseRepository {
3192
3259
  const relatedIds = [
3193
3260
  ...new Set(pivotRows.map((row) => row[relation.relatedPivotKey]))
3194
3261
  ];
3262
+ const limited = options.limit !== undefined || options.offset !== undefined;
3263
+ const ownerAlias = "__strata_pivot_parent_id";
3264
+ const bounded = limited ? {
3265
+ ...options,
3266
+ joins: [
3267
+ ...options.joins ?? [],
3268
+ {
3269
+ type: "inner",
3270
+ table: relation.pivotTable,
3271
+ on: [
3272
+ {
3273
+ left: { table: relatedRepository.table.name, column: relation.relatedKey },
3274
+ right: { table: relation.pivotTable, column: relation.relatedPivotKey }
3275
+ }
3276
+ ]
3277
+ }
3278
+ ],
3279
+ whereNodes: [
3280
+ ...options.whereNodes ?? [],
3281
+ {
3282
+ kind: "and",
3283
+ where: {
3284
+ [`${relation.pivotTable}.${relation.foreignPivotKey}`]: parentIds
3285
+ }
3286
+ }
3287
+ ],
3288
+ [RELATION_WINDOW]: {
3289
+ table: relation.pivotTable,
3290
+ column: relation.foreignPivotKey,
3291
+ ownerAlias
3292
+ }
3293
+ } : options;
3195
3294
  const relatedRows = await relatedRepository.withConnection(this.connection).findWhere({
3196
3295
  [relation.relatedKey]: relatedIds
3197
- }, options);
3296
+ }, bounded);
3297
+ if (limited) {
3298
+ return indexHasManyThroughRelation(parents, relatedRows, {
3299
+ type: "hasManyThrough",
3300
+ name: relation.name,
3301
+ localKey: relation.parentKey,
3302
+ throughTable: relation.pivotTable,
3303
+ firstKey: relation.foreignPivotKey,
3304
+ secondLocalKey: relation.relatedPivotKey,
3305
+ secondKey: relation.relatedKey,
3306
+ throughParentKey: ownerAlias
3307
+ });
3308
+ }
3198
3309
  return indexBelongsToManyRelation(parents, pivotRows, relatedRows, relation);
3199
3310
  }
3200
3311
  }
@@ -543,22 +543,33 @@ class SimpleCache {
543
543
  this.evictOverflow();
544
544
  }
545
545
  async getOrSet(key, loader, ttlMs) {
546
+ return this.getOrSetTagged(key, loader, [], ttlMs);
547
+ }
548
+ async getOrSetTagged(key, loader, tags, ttlMs) {
546
549
  this.pruneExpired();
547
550
  const cachedEntry = this.getFreshEntry(key);
548
551
  if (cachedEntry) {
552
+ this.attachTags(key, tags);
549
553
  return cachedEntry.value;
550
554
  }
551
555
  const inflightRequest = this.inflight.get(key);
552
556
  if (inflightRequest) {
557
+ this.attachTags(key, tags);
553
558
  return inflightRequest;
554
559
  }
555
- const pendingRequest = loader().then((value) => {
556
- this.set(key, value, ttlMs);
560
+ const pendingRequest = Promise.resolve().then(loader).then((value) => {
561
+ if (this.inflight.get(key) === pendingRequest)
562
+ this.set(key, value, ttlMs);
557
563
  return value;
558
564
  }).finally(() => {
559
- this.inflight.delete(key);
565
+ if (this.inflight.get(key) === pendingRequest) {
566
+ this.inflight.delete(key);
567
+ if (!this.cache.has(key))
568
+ this.detachKeyFromTags(key);
569
+ }
560
570
  });
561
571
  this.inflight.set(key, pendingRequest);
572
+ this.attachTags(key, tags);
562
573
  return pendingRequest;
563
574
  }
564
575
  attachTags(key, tags) {
@@ -604,14 +615,13 @@ class SimpleCache {
604
615
  }
605
616
  invalidate(key) {
606
617
  const removed = this.cache.delete(key);
607
- if (removed) {
608
- this.detachKeyFromTags(key);
609
- }
618
+ this.inflight.delete(key);
619
+ this.detachKeyFromTags(key);
610
620
  return removed;
611
621
  }
612
622
  invalidateByPrefix(prefix) {
613
623
  let removed = 0;
614
- for (const key of [...this.cache.keys()]) {
624
+ for (const key of new Set([...this.cache.keys(), ...this.inflight.keys()])) {
615
625
  if (key === prefix || key.startsWith(`${prefix}?`)) {
616
626
  if (this.invalidate(key)) {
617
627
  removed += 1;
@@ -702,6 +712,9 @@ class SimpleCacheStore {
702
712
  getOrSet(key, loader, ttlMs) {
703
713
  return this.cache.getOrSet(key, loader, ttlMs);
704
714
  }
715
+ getOrSetTagged(key, loader, tags, ttlMs) {
716
+ return this.cache.getOrSetTagged(key, loader, tags, ttlMs);
717
+ }
705
718
  attachTags(key, tags) {
706
719
  this.cache.attachTags(key, tags);
707
720
  return Promise.resolve();
@@ -31,22 +31,33 @@ class SimpleCache {
31
31
  this.evictOverflow();
32
32
  }
33
33
  async getOrSet(key, loader, ttlMs) {
34
+ return this.getOrSetTagged(key, loader, [], ttlMs);
35
+ }
36
+ async getOrSetTagged(key, loader, tags, ttlMs) {
34
37
  this.pruneExpired();
35
38
  const cachedEntry = this.getFreshEntry(key);
36
39
  if (cachedEntry) {
40
+ this.attachTags(key, tags);
37
41
  return cachedEntry.value;
38
42
  }
39
43
  const inflightRequest = this.inflight.get(key);
40
44
  if (inflightRequest) {
45
+ this.attachTags(key, tags);
41
46
  return inflightRequest;
42
47
  }
43
- const pendingRequest = loader().then((value) => {
44
- this.set(key, value, ttlMs);
48
+ const pendingRequest = Promise.resolve().then(loader).then((value) => {
49
+ if (this.inflight.get(key) === pendingRequest)
50
+ this.set(key, value, ttlMs);
45
51
  return value;
46
52
  }).finally(() => {
47
- this.inflight.delete(key);
53
+ if (this.inflight.get(key) === pendingRequest) {
54
+ this.inflight.delete(key);
55
+ if (!this.cache.has(key))
56
+ this.detachKeyFromTags(key);
57
+ }
48
58
  });
49
59
  this.inflight.set(key, pendingRequest);
60
+ this.attachTags(key, tags);
50
61
  return pendingRequest;
51
62
  }
52
63
  attachTags(key, tags) {
@@ -92,14 +103,13 @@ class SimpleCache {
92
103
  }
93
104
  invalidate(key) {
94
105
  const removed = this.cache.delete(key);
95
- if (removed) {
96
- this.detachKeyFromTags(key);
97
- }
106
+ this.inflight.delete(key);
107
+ this.detachKeyFromTags(key);
98
108
  return removed;
99
109
  }
100
110
  invalidateByPrefix(prefix) {
101
111
  let removed = 0;
102
- for (const key of [...this.cache.keys()]) {
112
+ for (const key of new Set([...this.cache.keys(), ...this.inflight.keys()])) {
103
113
  if (key === prefix || key.startsWith(`${prefix}?`)) {
104
114
  if (this.invalidate(key)) {
105
115
  removed += 1;
@@ -15,6 +15,9 @@ class SimpleCacheStore {
15
15
  getOrSet(key, loader, ttlMs) {
16
16
  return this.cache.getOrSet(key, loader, ttlMs);
17
17
  }
18
+ getOrSetTagged(key, loader, tags, ttlMs) {
19
+ return this.cache.getOrSetTagged(key, loader, tags, ttlMs);
20
+ }
18
21
  attachTags(key, tags) {
19
22
  this.cache.attachTags(key, tags);
20
23
  return Promise.resolve();
@@ -394,6 +394,42 @@ function buildSelectQuery(table, options = {}, whereNodes = []) {
394
394
  params
395
395
  };
396
396
  }
397
+ var EAGER_ROW_NUMBER = "__strata_eager_row_number";
398
+ function buildLimitedRelationQuery(table, options, partition, source) {
399
+ if (options.lock || options.groupBy?.length || options.having) {
400
+ throw new Error("Limited eager relations do not support row locks, grouping or HAVING.");
401
+ }
402
+ if (table.columns.includes(EAGER_ROW_NUMBER) || options.select?.some((item) => ("as" in item) && item.as === EAGER_ROW_NUMBER)) {
403
+ throw new Error(`Reserved eager relation column: ${EAGER_ROW_NUMBER}`);
404
+ }
405
+ buildLimitClause(options.limit);
406
+ buildOffsetClause(options.offset);
407
+ if (!Number.isSafeInteger((options.offset ?? 0) + (options.limit ?? 0))) {
408
+ throw new Error("Limited eager relation bounds must fit a safe integer.");
409
+ }
410
+ const order = [...normalizeOrderBy(options.orderBy ?? table.defaultOrderBy)];
411
+ if (!order.some((item) => item.column === table.primaryKey || item.column === `${table.name}.${table.primaryKey}`)) {
412
+ order.push({ column: table.primaryKey, direction: "ASC" });
413
+ }
414
+ const ordering = buildOrderByClause(table.name, order);
415
+ const params = [];
416
+ const columns = buildSelectList(table, options.select, params);
417
+ const rank = `ROW_NUMBER() OVER (PARTITION BY ${qualifyColumn(partition.table, partition.column)}${ordering}) AS ${quoteIdentifier(EAGER_ROW_NUMBER)}`;
418
+ const sql = source(columns, rank, params);
419
+ const offset = options.offset ?? 0;
420
+ const upper = options.limit === undefined ? "" : ` AND ${quoteIdentifier(EAGER_ROW_NUMBER)} <= ${offset + options.limit}`;
421
+ return {
422
+ text: `SELECT * FROM (${sql}) AS ${quoteIdentifier("__strata_eager")} WHERE ${quoteIdentifier(EAGER_ROW_NUMBER)} > ${offset}${upper} ORDER BY ${quoteIdentifier(EAGER_ROW_NUMBER)}`,
423
+ params
424
+ };
425
+ }
426
+ function buildLimitedHasManyQuery(table, options, partition) {
427
+ return buildLimitedRelationQuery(table, options, partition, (columns, rank, params) => {
428
+ const { clause } = buildQueryWhereClause(table, options, options.whereNodes, params);
429
+ const owner = partition.ownerAlias ? `, ${qualifyColumn(partition.table, partition.column)} AS ${quoteIdentifier(partition.ownerAlias)}` : "";
430
+ return `SELECT ${columns}${owner}, ${rank} FROM ${quoteIdentifier(table.name)}${buildJoinClause(options.joins)}${clause}`;
431
+ });
432
+ }
397
433
  function buildCountQuery(table, where = {}, options = {}, whereNodes = []) {
398
434
  const params = [];
399
435
  const { clause, params: whereParams } = buildQueryWhereClause(table, {
@@ -616,6 +652,7 @@ function buildConditionalWriteQuery(table, operation, changes, options, returnin
616
652
  };
617
653
  }
618
654
  export {
655
+ EAGER_ROW_NUMBER,
619
656
  assertSafeProjectionExpression,
620
657
  buildAdvancedWhereClause,
621
658
  buildConditionalWriteQuery,
@@ -626,6 +663,8 @@ export {
626
663
  buildIncrementQuery,
627
664
  buildInsertQuery,
628
665
  buildJoinClause,
666
+ buildLimitedHasManyQuery,
667
+ buildLimitedRelationQuery,
629
668
  buildOrderByClause,
630
669
  buildProjectionQuery,
631
670
  buildQueryWhereClause,
@@ -418,6 +418,42 @@ function buildSelectQuery(table, options = {}, whereNodes = []) {
418
418
  params
419
419
  };
420
420
  }
421
+ var EAGER_ROW_NUMBER = "__strata_eager_row_number";
422
+ function buildLimitedRelationQuery(table, options, partition, source) {
423
+ if (options.lock || options.groupBy?.length || options.having) {
424
+ throw new Error("Limited eager relations do not support row locks, grouping or HAVING.");
425
+ }
426
+ if (table.columns.includes(EAGER_ROW_NUMBER) || options.select?.some((item) => ("as" in item) && item.as === EAGER_ROW_NUMBER)) {
427
+ throw new Error(`Reserved eager relation column: ${EAGER_ROW_NUMBER}`);
428
+ }
429
+ buildLimitClause(options.limit);
430
+ buildOffsetClause(options.offset);
431
+ if (!Number.isSafeInteger((options.offset ?? 0) + (options.limit ?? 0))) {
432
+ throw new Error("Limited eager relation bounds must fit a safe integer.");
433
+ }
434
+ const order = [...normalizeOrderBy(options.orderBy ?? table.defaultOrderBy)];
435
+ if (!order.some((item) => item.column === table.primaryKey || item.column === `${table.name}.${table.primaryKey}`)) {
436
+ order.push({ column: table.primaryKey, direction: "ASC" });
437
+ }
438
+ const ordering = buildOrderByClause(table.name, order);
439
+ const params = [];
440
+ const columns = buildSelectList(table, options.select, params);
441
+ const rank = `ROW_NUMBER() OVER (PARTITION BY ${qualifyColumn(partition.table, partition.column)}${ordering}) AS ${quoteIdentifier(EAGER_ROW_NUMBER)}`;
442
+ const sql = source(columns, rank, params);
443
+ const offset = options.offset ?? 0;
444
+ const upper = options.limit === undefined ? "" : ` AND ${quoteIdentifier(EAGER_ROW_NUMBER)} <= ${offset + options.limit}`;
445
+ return {
446
+ text: `SELECT * FROM (${sql}) AS ${quoteIdentifier("__strata_eager")} WHERE ${quoteIdentifier(EAGER_ROW_NUMBER)} > ${offset}${upper} ORDER BY ${quoteIdentifier(EAGER_ROW_NUMBER)}`,
447
+ params
448
+ };
449
+ }
450
+ function buildLimitedHasManyQuery(table, options, partition) {
451
+ return buildLimitedRelationQuery(table, options, partition, (columns, rank, params) => {
452
+ const { clause } = buildQueryWhereClause(table, options, options.whereNodes, params);
453
+ const owner = partition.ownerAlias ? `, ${qualifyColumn(partition.table, partition.column)} AS ${quoteIdentifier(partition.ownerAlias)}` : "";
454
+ return `SELECT ${columns}${owner}, ${rank} FROM ${quoteIdentifier(table.name)}${buildJoinClause(options.joins)}${clause}`;
455
+ });
456
+ }
421
457
  function buildCountQuery(table, where = {}, options = {}, whereNodes = []) {
422
458
  const params = [];
423
459
  const { clause, params: whereParams } = buildQueryWhereClause(table, {
@@ -1185,11 +1221,12 @@ class RepositoryQuery {
1185
1221
  return await this.attach(rows);
1186
1222
  }
1187
1223
  async paginate(options) {
1188
- return await this.repository.paginate({
1224
+ const page = await this.repository.paginate({
1189
1225
  ...this.buildOptions(),
1190
1226
  page: options.page,
1191
1227
  perPage: options.perPage
1192
1228
  });
1229
+ return { ...page, data: await this.attach(page.data) };
1193
1230
  }
1194
1231
  async chunk(count, callback) {
1195
1232
  await this.repository.chunk(count, async (rows) => callback(await this.attach(rows)), this.buildOptions());
@@ -512,23 +512,25 @@ var {S3Client } = globalThis.Bun;
512
512
 
513
513
  // ../../src/core/security/safePath.ts
514
514
  import { isAbsolute, resolve, sep } from "path";
515
- function assertPathUnderRoot(rootDirectory, userPath) {
516
- const trimmed = userPath.trim();
517
- if (trimmed.length === 0) {
515
+ function resolvePathUnderRoot(rootDirectory, path) {
516
+ if (path.length === 0) {
518
517
  throw new Error("Path must not be empty.");
519
518
  }
520
- if (trimmed.includes("\x00")) {
519
+ if (path.includes("\x00")) {
521
520
  throw new Error("Path must not contain a null byte.");
522
521
  }
523
522
  const root = resolve(rootDirectory);
524
- const candidate = isAbsolute(trimmed) ? resolve(trimmed) : resolve(root, trimmed.replace(/^\/+/u, ""));
523
+ const candidate = isAbsolute(path) ? resolve(path) : resolve(root, path.replace(/^\/+/u, ""));
525
524
  if (candidate === root || candidate.startsWith(`${root}${sep}`)) {
526
525
  return candidate;
527
526
  }
528
527
  throw new Error("Path escapes the storage root.");
529
528
  }
529
+ function assertPathUnderRoot(rootDirectory, userPath) {
530
+ return resolvePathUnderRoot(rootDirectory, userPath.trim());
531
+ }
530
532
  function assertUrlPathUnderRoot(rootDirectory, urlPathname) {
531
- return assertPathUnderRoot(rootDirectory, urlPathname.replace(/^\/+/u, ""));
533
+ return resolvePathUnderRoot(rootDirectory, decodeURIComponent(urlPathname).replace(/^\/+/u, ""));
532
534
  }
533
535
 
534
536
  // ../../src/core/storage/storage.ts