feat: improve debuggability of SchemaRecord, RecordArray and Identifier

Author: runspired

guides/relationships/features/links-mode.md

@@ -60,6 +60,8 @@ interface LinksModeRelationship {
 }
 ```
 
+<br>
+
 ### Related Links May Be Provided by Handlers
 
 This means that, in order to use links mode, a relationship payload given to the cache MUST contain this related link. 
@@ -68,6 +70,8 @@ If your API does not provide this link, a [request handler](https://api.emberjs.
 
 Note that this approach can even work if your API requires you to send a POST request to fetch the relationship. [This blog post](https://runspired.com/2025/02/26/exploring-advanced-handlers.html) contains an overview of advanced request handling to achieve a similar aim for pagination.
 
+<br>
+
 ### When a Relationship Is Fetched, the Related Link Is Used
 
 Fetching a relationship via any of `relationship.reload`, `reference.reload`, `reference.load` or `await record.relationship` will issue a request to your handler chain. That request will look like the following:
@@ -106,12 +110,18 @@ relationship as well.
 
 Sideloads (included records) are valid to include in these responses.
 
+<br>
+
+---
+
 ## Activating LinksMode
 
 LinksMode is activated by adding `linksMode: true` to the relationship's options.
 
 Read on below for examples and nuances specific to Model vs SchemaRecord
 
+<br>
+
 ### For a Relationship on a Model
 
 ```ts
@@ -129,6 +139,8 @@ export default class User extends Model {
 
 This works for both `async` and `non-async` relationships and only changes the fetching behavior of the field it is defined on. For instance, in the example above, `homeAddress` is fetched in links mode while `<Address>.residents` might still be using the legacy adapter experience.
 
+<br>
+
 ### For a SchemaRecord in LegacyMode
 
 ```ts
@@ -155,6 +167,8 @@ const UserSchema = {
 The behavior of a relationship for a SchemaRecord in LegacyMode is always identical to that of a the same
 relationship defined on a Model.
 
+<br>
+
 ### For a SchemaRecord in PolarisMode
 
 ```ts
@@ -199,6 +213,10 @@ In the meantime, we've enabled synchronous linksMode relationships in order to a
 If this limitation is too great we would recommend continuing to use `LegacyMode` until the full story for 
 relationships in PolarisMode is shipped.
 
+<br>
+
+---
+
 #### What To Expect from PolarisMode Relationships in the Future
 
 We intend to replace `belongsTo` and `hasMany` fields with the (as yet not implemented)

guides/relationships/features/polymorphism.md

@@ -68,6 +68,10 @@ interface Human {
 }
 ```
 
+<br>
+
+---
+
 ## How To Implement
 
 WarpDrive implements polymorphism structurally: as long as records on both sides of the relationship agree
@@ -79,6 +83,8 @@ There are two polymorphic modes in WarpDrive:
 - **open** - any type of record can be a value (this is like our last example above of `pets: unknown[]`)
 - **closed** - only types of records that conform to a specific contract can be a value
 
+<br>
+
 ### Open Polymorphism
 
 To make any relationship an open polymorphic relationship, its options should include both `inverse: null` and 
@@ -117,6 +123,8 @@ store.schema.registerResource({
 })
 ```
 
+<br>
+
 ### Closed/Structural Polymorphism
 
 To make any relationship a closed polymorphic relationship based on structural contract, its options should
@@ -219,6 +227,10 @@ schema:
 }
 ```
 
+<br>
+
+---
+
 ## Fetching Polymorphic Data
 
 When working with a polymorphic relationship, the resource data for each related resource

packages/core-types/src/identifier.ts

@@ -9,12 +9,12 @@ export const DEBUG_CLIENT_ORIGINATED: unique symbol = Symbol('record-originated-
 export const DEBUG_IDENTIFIER_BUCKET: unique symbol = Symbol('identifier-bucket');
 export const DEBUG_STALE_CACHE_OWNER: unique symbol = Symbol('warpDriveStaleCache');
 
-function ProdSymbol<T extends string>(str: T): T {
-  return DEBUG ? (Symbol(str) as unknown as T) : str;
+function ProdSymbol<T extends string>(str: T, debugStr: string): T {
+  return DEBUG ? (Symbol(debugStr) as unknown as T) : str;
 }
 
 // also present in production
-export const CACHE_OWNER: '__$co' = ProdSymbol('__$co');
+export const CACHE_OWNER: '__$co' = ProdSymbol('__$co', 'CACHE_OWNER');
 
 export type IdentifierBucket = 'record' | 'document';
 

packages/schema-record/src/-private/record.ts

@@ -6,6 +6,7 @@ import type { NotificationType } from '@ember-data/store';
 import type { RelatedCollection as ManyArray } from '@ember-data/store/-private';
 import { recordIdentifierFor, setRecordIdentifier } from '@ember-data/store/-private';
 import { addToTransaction, entangleSignal, getSignal, type Signal, Signals } from '@ember-data/tracking/-private';
+import { DEBUG } from '@warp-drive/build-config/env';
 import { assert } from '@warp-drive/build-config/macros';
 import type { StableRecordIdentifier } from '@warp-drive/core-types';
 import type { ArrayValue, ObjectValue, Value } from '@warp-drive/core-types/json/raw';
@@ -688,6 +689,19 @@ export class SchemaRecord {
       }
     );
 
+    if (DEBUG) {
+      Object.defineProperty(proxy, '__SHOW_ME_THE_DATA_(debug mode only)__', {
+        get() {
+          const data: Record<string, unknown> = {};
+          for (const key of fields.keys()) {
+            data[key] = proxy[key as keyof SchemaRecord];
+          }
+
+          return data;
+        },
+      });
+    }
+
     return proxy;
   }
 

packages/store/src/-private/caches/identifier-cache.ts

@@ -650,16 +650,14 @@ function makeStableRecordIdentifier(
   if (DEBUG) {
     // we enforce immutability in dev
     //  but preserve our ability to do controlled updates to the reference
-    let wrapper: StableRecordIdentifier = {
-      get lid() {
-        return recordIdentifier.lid;
-      },
+    let wrapper = {
+      type: recordIdentifier.type,
+      lid: recordIdentifier.lid,
       get id() {
         return recordIdentifier.id;
       },
-      get type() {
-        return recordIdentifier.type;
-      },
+    } as StableRecordIdentifier;
+    const proto = {
       get [CACHE_OWNER](): number | undefined {
         return recordIdentifier[CACHE_OWNER];
       },
@@ -672,23 +670,22 @@ function makeStableRecordIdentifier(
       set [DEBUG_STALE_CACHE_OWNER](value: number | undefined) {
         (recordIdentifier as StableRecordIdentifier)[DEBUG_STALE_CACHE_OWNER] = value;
       },
-    };
-    Object.defineProperty(wrapper, 'toString', {
-      enumerable: false,
-      value: () => {
+      get [DEBUG_CLIENT_ORIGINATED]() {
+        return clientOriginated;
+      },
+      get [DEBUG_IDENTIFIER_BUCKET]() {
+        return bucket;
+      },
+      toString() {
         const { type, id, lid } = recordIdentifier;
         return `${clientOriginated ? '[CLIENT_ORIGINATED] ' : ''}${String(type)}:${String(id)} (${lid})`;
       },
-    });
-    Object.defineProperty(wrapper, 'toJSON', {
-      enumerable: false,
-      value: () => {
+      toJSON() {
         const { type, id, lid } = recordIdentifier;
         return { type, id, lid };
       },
-    });
-    wrapper[DEBUG_CLIENT_ORIGINATED] = clientOriginated;
-    wrapper[DEBUG_IDENTIFIER_BUCKET] = bucket;
+    };
+    Object.setPrototypeOf(wrapper, proto);
     DEBUG_MAP.set(wrapper, recordIdentifier);
     wrapper = freeze(wrapper);
     return wrapper;

packages/store/src/-private/record-arrays/identifier-array.ts

@@ -11,6 +11,7 @@ import {
   subscribe,
 } from '@ember-data/tracking/-private';
 import { DEPRECATE_COMPUTED_CHAINS } from '@warp-drive/build-config/deprecations';
+import { DEBUG } from '@warp-drive/build-config/env';
 import { assert } from '@warp-drive/build-config/macros';
 import { getOrSetGlobal } from '@warp-drive/core-types/-private';
 import type { LocalRelationshipOperation } from '@warp-drive/core-types/graph';
@@ -448,6 +449,14 @@ export class IdentifierArray<T = unknown> {
       },
     }) as IdentifierArray<T>;
 
+    if (DEBUG) {
+      Object.defineProperty(proxy, '__SHOW_ME_THE_DATA_(debug mode only)__', {
+        get() {
+          return proxy.slice();
+        },
+      });
+    }
+
     createArrayTags(proxy, _SIGNAL);
 
     this[NOTIFY] = this[NOTIFY].bind(proxy);

pnpm-lock.yaml

@@ -45,6 +45,7 @@
     "@glimmer/tracking": "^1.1.2",
     "@html-next/vertical-collection": "^4.0.2",
     "@types/morgan": "^1.9.9",
+    "@warp-drive/build-config": "workspace:*",
     "@warp-drive/core-types": "workspace:*",
     "@warp-drive/internal-config": "workspace:*",
     "ember-auto-import": "2.10.0",

tests/example-json-api/package.json

@@ -69,6 +69,7 @@
     "qunit-console-grouper": "^0.3.0",
     "qunit-dom": "^3.1.1",
     "silent-error": "^1.1.1",
+    "testem": "^3.12.0",
     "typescript": "^5.8.2",
     "webpack": "^5.98.0"
   },