@rebasepro/common 0.14.1 → 0.14.2-canary.gca521e9

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/common",
   "type": "module",
-  "version": "0.14.1",
+  "version": "0.14.2-canary.gca521e9",
   "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/types": "0.14.2-canary.gca521e9",
+    "@rebasepro/utils": "0.14.2-canary.gca521e9"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",

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`.")
         );
     }