Give records a reference to the model manager which loaded them

We have a few upcoming things that require records to be able to do stuff to themselves -- reload, select new fields from the backend, maybe `record.save` or similar, and I suspect more in the future. I still think they should act mostly as DTOs that don't have a lot of business logic on them, but if we want to be able to even know what model they are for, we need a reference to the thing that produced them! This passes along the model manager which instantiated a record to the record in both imperative API land and in React land.

In order to make this change work in React land, we need a new little bit of metadata exported from the generated client. Our React hooks get passed functions from the api client like `useAction(api.post.create)`, so we need to be able to hop back from the `create` function that we get by reference to the `api.post` object. The generated client will need to decorate the `create` function with a reference, which is not super hard, but means that we have a backwards compatibility issue. `@gadgetinc/react` can't assume that it is upgraded at the same time as the api client, so it can't assume it is working against a newly generated api client that has this metadata.

For this reason, the model manager property on `GadgetRecord` is optional, which reflects the way it will be used in the real world without necessarily having that metadata available. When we go to build things like `record.reload()`, we can make that fail at runtime with a message saying "regenerate your client to get this to work!", instead of just assuming it is present.

Author: garymardell

packages/api-client-core/spec/GadgetRecord.spec.ts

@@ -1,3 +1,4 @@
+import type { AnyPublicModelManager } from "../src/AnyModelManager.js";
 import { ChangeTracking, GadgetRecord } from "../src/GadgetRecord.js";
 interface SampleBaseRecord {
   id?: string;
@@ -38,6 +39,8 @@ const expectPersistedChanges = (record: GadgetRecord<SampleBaseRecord>, ...prope
   return _expectChanges(record, ChangeTracking.SinceLastPersisted, ...properties);
 };
 
+const mockModelManager: AnyPublicModelManager = {} as any;
+
 describe("GadgetRecord", () => {
   let productBaseRecord: SampleBaseRecord;
   beforeAll(() => {
@@ -48,6 +51,18 @@ describe("GadgetRecord", () => {
     };
   });
 
+  it("can be constructed with a base record and no model manager for backwards compatibility", () => {
+    const product = new GadgetRecord<SampleBaseRecord>(productBaseRecord);
+    expect(product.id).toEqual("123");
+    expect(product.name).toEqual("A cool product");
+    expect(product.modelManager).toEqual(null);
+  });
+
+  it("can be constructed with a base record and a model manager", () => {
+    const product = new GadgetRecord<SampleBaseRecord>(productBaseRecord, mockModelManager);
+    expect(product.modelManager).toEqual(mockModelManager);
+  });
+
   it("should respond toJSON, which returns the inner __gadget.fields properties", () => {
     const product = new GadgetRecord<SampleBaseRecord>(productBaseRecord);
     expect(product.toJSON()).toEqual({

packages/api-client-core/spec/operationRunners.spec.ts

@@ -4,7 +4,7 @@ import { diff } from "@n1ru4l/json-patch-plus";
 import { CombinedError } from "@urql/core";
 import nock from "nock";
 import { BackgroundActionHandle } from "../src/BackgroundActionHandle.js";
-import type { AnyModelManager, GadgetErrorGroup, LimitToKnownKeys } from "../src/index.js";
+import type { AnyPublicModelManager, GadgetErrorGroup, LimitToKnownKeys } from "../src/index.js";
 import {
   GadgetConnection,
   actionRunner,
@@ -30,7 +30,7 @@ describe("type checks", () => {
       options?: LimitToKnownKeys<Options, CreatePostOptions>
     ): Promise<CreatePostResult<Options>> {
       return await actionRunner<SelectedPostOrDefault<Options>>(
-        this,
+        this, // This is a problem...
         "createPost",
         DefaultPostSelection,
         "post",
@@ -48,6 +48,7 @@ describe("type checks", () => {
 // eslint-disable-next-line jest/no-export
 describe("operationRunners", () => {
   let connection: GadgetConnection;
+  let manager: AnyPublicModelManager;
   let query: string | undefined;
   let mockUrqlClient: MockUrqlClient;
 
@@ -60,6 +61,7 @@ describe("operationRunners", () => {
       },
     });
     jest.spyOn(connection, "currentClient" as any, "get").mockReturnValue(mockUrqlClient as any);
+    manager = { connection } as AnyPublicModelManager;
   });
 
   describe("findOneRunner", () => {
@@ -74,7 +76,7 @@ describe("operationRunners", () => {
                   __typename
                 }
                 gadgetMeta {
-                  hydrations(modelName: 
+                  hydrations(modelName:
               "widget")
                 }
               }"
@@ -114,7 +116,7 @@ describe("operationRunners", () => {
             }
           }
           gadgetMeta {
-            hydrations(modelName: 
+            hydrations(modelName:
         "outer.inner.widget")
           }
         }"
@@ -170,7 +172,7 @@ describe("operationRunners", () => {
             }
           }
           gadgetMeta {
-            hydrations(modelName: 
+            hydrations(modelName:
         "widget")
           }
         }"
@@ -240,7 +242,7 @@ describe("operationRunners", () => {
             }
           }
           gadgetMeta {
-            hydrations(modelName: 
+            hydrations(modelName:
         "outer.inner.widget")
           }
         }"
@@ -316,7 +318,7 @@ describe("operationRunners", () => {
 
   describe("findManyRunner", () => {
     test("can execute a findMany operation against a model", async () => {
-      const promise = findManyRunner({ connection } as AnyModelManager, "widgets", { id: true, name: true }, "widget");
+      const promise = findManyRunner({ connection } as AnyPublicModelManager, "widgets", { id: true, name: true }, "widget");
 
       expect(query).toMatchInlineSnapshot(`
               "query widgets($after: String, $first: Int, $before: String, $last: Int) {
@@ -337,7 +339,7 @@ describe("operationRunners", () => {
                   }
                 }
                 gadgetMeta {
-                  hydrations(modelName: 
+                  hydrations(modelName:
               "widget")
                 }
               }"
@@ -369,7 +371,7 @@ describe("operationRunners", () => {
 
     test("can execute a findMany operation against a namespaced model", async () => {
       const promise = findManyRunner(
-        { connection } as AnyModelManager,
+        { connection } as AnyPublicModelManager,
         "widgets",
         { id: true, name: true },
         "widget",
@@ -400,7 +402,7 @@ describe("operationRunners", () => {
             }
           }
           gadgetMeta {
-            hydrations(modelName: 
+            hydrations(modelName:
         "outer.inner.widget")
           }
         }"
@@ -436,7 +438,7 @@ describe("operationRunners", () => {
 
     test("can execute a findMany operation against a namespaced model when the namespace is a string", async () => {
       const promise = findManyRunner(
-        { connection } as AnyModelManager,
+        { connection } as AnyPublicModelManager,
         "widgets",
         { id: true, name: true },
         "widget",
@@ -466,7 +468,7 @@ describe("operationRunners", () => {
             }
           }
           gadgetMeta {
-            hydrations(modelName: 
+            hydrations(modelName:
         "outer.widget")
           }
         }"
@@ -502,9 +504,7 @@ describe("operationRunners", () => {
   describe("actionRunner", () => {
     test("can run a single create action", async () => {
       const promise = actionRunner<{ id: string; name: string }>(
-        {
-          connection,
-        },
+        manager,
         "createWidget",
         { id: true, name: true },
         "widget",
@@ -544,9 +544,7 @@ describe("operationRunners", () => {
 
     test("can run a single update action", async () => {
       const promise = actionRunner<{ id: string; name: string }>(
-        {
-          connection,
-        },
+        manager,
         "updateWidget",
         { id: true, name: true },
         "widget",
@@ -591,9 +589,7 @@ describe("operationRunners", () => {
 
     test("can run a single action with an object result type", async () => {
       const promise = actionRunner(
-        {
-          connection,
-        },
+        manager,
         "upsertWidget",
         { id: true, name: true, eventAt: true },
         "widget",
@@ -646,9 +642,7 @@ describe("operationRunners", () => {
 
     test("can run a single action with an object result type that has an inner return type", async () => {
       const promise = actionRunner(
-        {
-          connection,
-        },
+        manager,
         "upsertWidget",
         { id: true, name: true, eventAt: true },
         "widget",
@@ -693,9 +687,7 @@ describe("operationRunners", () => {
 
     test("can run an action with hasReturnType", async () => {
       const promise = actionRunner(
-        {
-          connection,
-        },
+        manager,
         "createWidget",
         { id: true, name: true },
         "widget",
@@ -733,9 +725,7 @@ describe("operationRunners", () => {
 
     test("can throw the error returned by the server for a single action", async () => {
       const promise = actionRunner<{ id: string; name: string }>(
-        {
-          connection,
-        },
+        manager,
         "updateWidget",
         { id: true, name: true },
         "widget",
@@ -780,9 +770,7 @@ describe("operationRunners", () => {
 
     test("can run a bulk action by ids", async () => {
       const promise = actionRunner<{ id: string; name: string }>(
-        {
-          connection,
-        },
+        manager,
         "bulkFlipWidgets",
         { id: true, name: true },
         "widget",
@@ -830,9 +818,7 @@ describe("operationRunners", () => {
 
     test("can run a bulk action with params", async () => {
       const promise = actionRunner<{ id: string; name: string }>(
-        {
-          connection,
-        },
+        manager,
         "bulkCreateWidgets",
         { id: true, name: true },
         "widget",
@@ -880,9 +866,7 @@ describe("operationRunners", () => {
 
     test("can run a bulk action with a returnType", async () => {
       const promise = actionRunner(
-        {
-          connection,
-        },
+        manager,
         "bulkCreateWidgets",
         { id: true, name: true },
         "widget",
@@ -921,9 +905,7 @@ describe("operationRunners", () => {
 
     test("can run a bulk action with an object returnType", async () => {
       const promise = actionRunner(
-        {
-          connection,
-        },
+        manager,
         "bulkUpsertWidgets",
         { id: true, name: true },
         "widget",
@@ -970,9 +952,7 @@ describe("operationRunners", () => {
 
     test("throws a nice error when a bulk action returns errors", async () => {
       const promise = actionRunner<{ id: string; name: string }>(
-        {
-          connection,
-        },
+        manager,
         "bulkCreateWidgets",
         { id: true, name: true },
         "widget",
@@ -1010,9 +990,7 @@ describe("operationRunners", () => {
 
     test("throws a nice error when a bulk action returns errors and data", async () => {
       const promise = actionRunner<{ id: string; name: string }>(
-        {
-          connection,
-        },
+        manager,
         "bulkCreateWidgets",
         { id: true, name: true },
         "widget",
@@ -1057,9 +1035,7 @@ describe("operationRunners", () => {
 
     test("returns undefined when bulk action does not have a result", async () => {
       const promise = actionRunner<{ id: string; name: string }>(
-        {
-          connection,
-        },
+        manager,
         "bulkDeleteWidgets",
         null,
         "widget",
@@ -1958,7 +1934,7 @@ describe("operationRunners", () => {
       test("can run a live findMany", async () => {
         const iterator = asyncIterableToIterator(
           findManyRunner<{ id: string; name: string }, { live: true }>(
-            { connection } as AnyModelManager,
+            { connection } as AnyPublicModelManager,
             "widgets",
             { id: true, name: true },
             "widget",

packages/api-client-core/src/ModelManager.ts renamed to packages/api-client-core/src/AnyModelManager.ts

@@ -1,6 +1,7 @@
 import type { GadgetConnection } from "./GadgetConnection.js";
 import type { GadgetRecord } from "./GadgetRecord.js";
 import type { GadgetRecordList } from "./GadgetRecordList.js";
+import type { InternalModelManager } from "./InternalModelManager.js";
 
 export type AnyModelFinderMetadata = {
   /** The name of the GraphQL API field that should be called for this operation */
@@ -20,13 +21,35 @@ export type AnyModelFinderMetadata = {
 };
 
 /**
- * Object representing one model's API in a high level way
- * This is a generic interface. Concrete ones are generated by Gadget, */
-export interface AnyModelManager {
+ * The manager class for a given model that uses the Public API, like `api.post` or `api.user`
+ **/
+export interface AnyPublicModelManager {
   connection: GadgetConnection;
+  apiIdentifier?: string;
   findOne: ((id: string, options: any) => Promise<GadgetRecord<any>>) & AnyModelFinderMetadata;
   findMany: ((options: any) => Promise<GadgetRecordList<any>>) & AnyModelFinderMetadata;
   findFirst: ((options: any) => Promise<GadgetRecord<any>>) & AnyModelFinderMetadata;
   maybeFindFirst(options: any): Promise<GadgetRecord<any> | null>;
   maybeFindOne(id: string, options: any): Promise<GadgetRecord<any> | null>;
 }
+
+/**
+ * The manager class for a given single model that uses the Public API, like `api.session`
+ **/
+export interface AnyPublicSingletonModelManager {
+  connection: GadgetConnection;
+  apiIdentifier?: string;
+  get(): Promise<GadgetRecord<any>>;
+}
+
+/**
+ * Prior to 1.1 actions were defined to accept just a connection
+ */
+export interface AnyLegacyModelManager {
+  connection: GadgetConnection;
+}
+
+/**
+ * Any model manager, either public or internal
+ */
+export type AnyModelManager = AnyPublicModelManager | AnyPublicSingletonModelManager | AnyLegacyModelManager | InternalModelManager;