@rebasepro/common 0.14.1 → 0.14.2-canary.g27a129e

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/common",
   "type": "module",
-  "version": "0.14.1",
+  "version": "0.14.2-canary.g27a129e",
   "description": "Rebase shared core — collection registry, data driver adapter and fluent query builder. No React dependency.",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -40,8 +40,8 @@
   "dependencies": {
     "fast-equals": "6.0.2",
     "json-logic-js": "^2.0.5",
-    "@rebasepro/types": "0.14.1",
-    "@rebasepro/utils": "0.14.1"
+    "@rebasepro/utils": "0.14.2-canary.g27a129e",
+    "@rebasepro/types": "0.14.2-canary.g27a129e"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",

package/src/data/sort-dialect.ts

@@ -1,4 +1,5 @@
-import type { OrderBySpec, OrderByTuple } from "@rebasepro/types";
+import type { OrderBySortTuple, OrderBySpec, OrderByTuple } from "@rebasepro/types";
+import { isRelationAggregateSort, sortKeyToString } from "@rebasepro/types";
 
 /**
  * Sort-order wire codec.
@@ -20,16 +21,27 @@ import type { OrderBySpec, OrderByTuple } from "@rebasepro/types";
  * the same value; the two are told apart by whether the first element is
  * itself an array, which no field name ever is.
  *
+ * This is also where a {@link RelationAggregateSort} object stops being an
+ * object. Above this function a sort key may be either spelling; below it,
+ * every key is a string — which is what `OrderByTuple`, the REST parameter, the
+ * driver contract and the cursor all already were. Doing it here means the one
+ * place that already collapses the two *shapes* of a sort also collapses the
+ * two *spellings* of a key, rather than every consumer learning about both.
+ *
  * @returns The keys in order of significance, or `undefined` for no sort. An
  *   empty list also returns `undefined` — "sort by nothing" is no sort, and
  *   letting `[]` through would have every layer below re-deciding what it meant.
  */
 export function normalizeOrderBy(orderBy?: OrderBySpec): OrderByTuple[] | undefined {
     if (!orderBy || orderBy.length === 0) return undefined;
+    // An aggregate key is an object, so the first element being an array still
+    // tells the list form from the single-tuple one — no field name is an
+    // array, and neither is an aggregate key.
     const list = Array.isArray(orderBy[0])
-        ? orderBy as OrderByTuple[]
-        : [orderBy as OrderByTuple];
-    return list.length > 0 ? list : undefined;
+        ? orderBy as OrderBySortTuple[]
+        : [orderBy as OrderBySortTuple];
+    if (list.length === 0) return undefined;
+    return list.map(([key, direction]) => [sortKeyToString(key), direction] as OrderByTuple);
 }
 
 /**
@@ -99,21 +111,30 @@ export function parseOrderBySpecStrict(raw: unknown, order?: "asc" | "desc"): Or
         throw new OrderBySpecError(`${typeof raw} is not a field name or a list of sort keys`);
     }
 
-    // The single-tuple spelling, `["created_at", "desc"]`.
-    if (typeof raw[0] === "string") return [toStrictTuple(raw, 0)];
+    // The single-tuple spelling, `["created_at", "desc"]` — or the same shape
+    // with an aggregate key in place of the field name.
+    if (typeof raw[0] === "string" || isRelationAggregateSort(raw[0])) return [toStrictTuple(raw, 0)];
 
     return raw.map(toStrictTuple);
 }
 
 function toStrictTuple(raw: unknown, index: number): OrderByTuple {
-    if (!Array.isArray(raw) || typeof raw[0] !== "string" || raw[0].trim() === "") {
+    if (!Array.isArray(raw)) {
+        throw new OrderBySpecError(`entry ${index} has no field name`);
+    }
+    // The object spelling of an aggregate key, from an untyped caller that did
+    // not go through `normalizeOrderBy`. Encoded rather than refused: it is a
+    // sort this understands, and rejecting the shape a typed caller writes
+    // would be a distinction between the two spellings that nothing else makes.
+    const key = isRelationAggregateSort(raw[0]) ? sortKeyToString(raw[0]) : raw[0];
+    if (typeof key !== "string" || key.trim() === "") {
         throw new OrderBySpecError(`entry ${index} has no field name`);
     }
     const direction = raw[1];
     if (direction !== undefined && direction !== "asc" && direction !== "desc") {
         throw new OrderBySpecError(`entry ${index} has direction '${String(direction)}'`);
     }
-    return [raw[0], direction ?? "asc"];
+    return [key, direction ?? "asc"];
 }
 
 /**
@@ -143,6 +164,9 @@ export function serializeOrderBy(orderBy?: OrderBySpec | string): string | undef
     if (!orderBy) return undefined;
     // Runtime tolerance: pass through a pre-serialized wire string unchanged.
     if (typeof orderBy === "string") return orderBy;
+    // `normalizeOrderBy` has already encoded any aggregate key to its string
+    // spelling, which is why the shorthand below can assume a string: neither
+    // `min(applications.created_at)` nor `count(applications)` contains a `:`.
     const list = normalizeOrderBy(orderBy);
     if (!list) return undefined;
     if (list.length === 1) return `${list[0][0]}:${list[0][1]}`;

package/src/util/internal-tables.ts

@@ -80,6 +80,7 @@ export const REBASE_INTERNAL_TABLES: readonly string[] = [
     "api_keys",
     "cron_logs",
     "cron_claims",
+    "rate_limit_hits",
     "idempotency_keys",
     "entity_history",
     "branches",

package/src/util/resolve-relation.ts

@@ -46,7 +46,14 @@ export function resolveRelation(
 
     const shared: Pick<ResolvedRelation, "relationName" | "target" | "targetSlug" | "onUpdate" | "onDelete" | "overrides" | "validation"> = {
         relationName,
-        target,
+        // Normalised, not the thunk as written. Resolution reads the target once
+        // and every later consumer calls it again — the driver building a join,
+        // the DDL and policy generators, the admin's relation fields — so
+        // handing back the raw thunk would give all of them the module namespace
+        // `callTarget` just looked past, and the fix would hold only for the
+        // fields resolution happens to read here. Still lazy: same call at the
+        // same moment, one unwrap on the way out.
+        target: () => unwrapModuleNamespace(target()) as CollectionConfig,
         targetSlug: targetCollection.slug,
         onUpdate: relation.onUpdate,
         onDelete: relation.onDelete,
@@ -139,25 +146,58 @@ function describe(relation: Relation, sourceCollection: CollectionConfig, proper
 }
 
 /**
- * Call the `target` thunk, and translate the two ways an import cycle breaks it
- * into an error that names the cause.
+ * A module namespace, unwrapped to the collection it exports.
+ *
+ * A cycle transpiled to CommonJS does not hand the importing module the
+ * *default export* — it hands it the module object, `{ __esModule: true,
+ * default: … }`, captured before the exporting module finished evaluating. The
+ * `default` slot fills in later, so by the time a lazy `target` thunk runs the
+ * collection is sitting right there, one level down. Returning the namespace is
+ * never a thing a thunk means to do, and there is exactly one reading of it.
+ *
+ * Only unwrapped when the inner value is itself a collection: a `default` that
+ * is not one is a genuinely wrong thunk, and it should reach the error below
+ * rather than be quietly swapped in.
+ */
+function unwrapModuleNamespace(value: unknown): unknown {
+    if (!value || typeof value !== "object") return value;
+    if ((value as { slug?: unknown }).slug) return value;
+    const inner = (value as { default?: unknown }).default;
+    return inner && typeof inner === "object" && (inner as { slug?: unknown }).slug ? inner : value;
+}
+
+/**
+ * Call the `target` thunk, and translate the ways an import cycle breaks it into
+ * an error that names the cause — or, where the value is recoverable, into the
+ * collection the thunk meant.
  *
  * The thunk exists to defer the reference until every module has finished
- * evaluating, and for a cycle that closes at import time it does. What it cannot
- * defer is a cycle that leaves the binding permanently unusable, and there are
- * two shapes of that:
+ * evaluating, and for a cycle that closes at import time it does. Two cycles
+ * leave the binding permanently unusable:
  *
  *  - **ESM/TDZ.** `const` and `class` bindings in a not-yet-evaluated module are
  *    in the temporal dead zone, so reading one throws `ReferenceError: x is not
  *    defined`. The stack points at the thunk — a one-line arrow function that is
  *    obviously fine — and says nothing about the cycle that made it throw.
- *  - **CJS interop.** The half-initialised module object has no `default` yet,
- *    the import resolves to `undefined`, and the thunk returns it without
- *    complaint. That one used to surface here as "did not resolve to a
+ *  - **CJS interop, unresolved.** The half-initialised module object has no
+ *    `default` yet, the import resolves to `undefined`, and the thunk returns it
+ *    without complaint. That one used to surface here as "did not resolve to a
  *    collection", which is true and unhelpful.
  *
  * Both mean the same thing, and the fix for both is the same: break the cycle,
  * or move the relation into the collection that does not close it.
+ *
+ * A third shape is *not* an error, and used to be reported as one. A loader that
+ * transpiles ESM to CJS — jiti, which is what `rebase generate-sdk` and
+ * `rebase build` load collections with — gives the module entered second in a
+ * cycle a namespace object rather than the default export, and never replaces it
+ * with a live binding. The thunk then returns `{ __esModule: true, default: … }`
+ * holding the fully-initialised collection. Native ESM resolves the same thunk
+ * to the collection directly, so this was a loader artefact reported as an
+ * authoring mistake, and the advice it gave — make the target a lazy thunk — was
+ * already satisfied by the code it was rejecting. Bidirectional relations make
+ * these cycles unavoidable, and the lazy thunk is this framework's own answer to
+ * them, so {@link unwrapModuleNamespace} takes the collection and moves on.
  */
 function callTarget(
     relation: Relation,
@@ -167,7 +207,7 @@ function callTarget(
 ): ReturnType<Relation["target"]> {
     let targetCollection: ReturnType<Relation["target"]> | undefined;
     try {
-        targetCollection = target();
+        targetCollection = unwrapModuleNamespace(target()) as ReturnType<Relation["target"]>;
     } catch (error) {
         // A ReferenceError from inside the thunk is a binding that was never
         // initialised — nothing else in a one-expression arrow can raise one.
@@ -191,7 +231,11 @@ function callTarget(
                 ? "Under CommonJS interop an import cycle resolves the default import to `undefined`, " +
                   "so check whether this collection and its target import each other. Otherwise the thunk " +
                   "is returning the wrong value — it must return the collection itself, not a promise or a module."
-                : "The thunk must return a collection config with a `slug`.")
+                : typeof (targetCollection as { then?: unknown }).then === "function"
+                    ? "The thunk returned a promise — `target: () => import(\"./other\")` is asynchronous. " +
+                      "Import the collection at the top of the file and return the binding: " +
+                      "`target: () => otherCollection`."
+                    : "The thunk must return a collection config with a `slug`.")
         );
     }