chore: begin work on consumer types

Author: runspired

packages/core-types/src/record.ts

@@ -0,0 +1,36 @@
+/**
+ * @module @warp-drive/core-types
+ */
+import type { ResourceType } from 'symbols';
+
+/**
+ * Records may be anything, They don't even
+ * have to be objects.
+ *
+ * Whatever they are, if they have a ResourceType
+ * property, that property will be used by EmberData
+ * and WarpDrive to provide better type safety and
+ * intellisense.
+ *
+ * @class TypedRecordInstance
+ */
+export interface TypedRecordInstance {
+  /**
+   * The type of the resource.
+   *
+   * This is an optional feature that can be used by
+   * record implementations to provide a typescript
+   * hint for the type of the resource.
+   *
+   * When used, EmberData and WarpDrive APIs can
+   * take advantage of this to provide better type
+   * safety and intellisense.
+   *
+   * @property {ResourceType} [ResourceType]
+   * @type {string}
+   *
+   */
+  [ResourceType]?: string;
+}
+
+export type TypeFromInstance<T> = T extends TypedRecordInstance ? T[typeof ResourceType] : never;

packages/core-types/src/spec/raw.ts

@@ -27,9 +27,9 @@ export interface PaginationLinks extends Links {
  * [JSON:API Spec](https://jsonapi.org/format/#document-resource-identifier-objects)
  * @internal
  */
-export interface ExistingResourceIdentifierObject {
+export interface ExistingResourceIdentifierObject<T extends string = string> {
   id: string;
-  type: string;
+  type: T;
 
   /**
    * While not officially part of the `JSON:API` spec,
@@ -65,7 +65,7 @@ export interface ExistingResourceIdentifierObject {
  *
  * @internal
  */
-export interface NewResourceIdentifierObject {
+export interface NewResourceIdentifierObject<T extends string = string> {
   /**
    * Resources newly created on the client _may_
    * not have an `id` available to them prior
@@ -76,7 +76,7 @@ export interface NewResourceIdentifierObject {
    * @internal
    */
   id: string | null;
-  type: string;
+  type: T;
 
   /**
    * Resources newly created on the client _will always_
@@ -90,10 +90,10 @@ export interface ResourceIdentifier {
   lid: string;
 }
 
-export type ResourceIdentifierObject =
+export type ResourceIdentifierObject<T extends string = string> =
   | ResourceIdentifier
-  | ExistingResourceIdentifierObject
-  | NewResourceIdentifierObject;
+  | ExistingResourceIdentifierObject<T>
+  | NewResourceIdentifierObject<T>;
 
 // TODO disallow NewResource, make narrowable
 export interface SingleResourceRelationship {

packages/core-types/src/symbols.ts

@@ -1 +1,19 @@
+/**
+ * @module @warp-drive/core-types
+ */
 export const RecordStore = Symbol('Store');
+
+/**
+ * Symbol for the type of a resource.
+ *
+ * This is an optional feature that can be used by
+ * record implementations to provide a typescript
+ * hint for the type of the resource.
+ *
+ * When used, EmberData and WarpDrive APIs can
+ * take advantage of this to provide better type
+ * safety and intellisense.
+ *
+ * @type {Symbol}
+ */
+export const ResourceType = Symbol('$type');

packages/store/src/-private/store-service.ts

@@ -15,6 +15,7 @@ import type {
   StableExistingRecordIdentifier,
   StableRecordIdentifier,
 } from '@warp-drive/core-types/identifier';
+import type { TypedRecordInstance, TypeFromInstance } from '@warp-drive/core-types/record';
 import { EnableHydration, SkipCache } from '@warp-drive/core-types/request';
 import type { ResourceDocument } from '@warp-drive/core-types/spec/document';
 import type {
@@ -24,6 +25,7 @@ import type {
   ResourceIdentifierObject,
   SingleResourceDocument,
 } from '@warp-drive/core-types/spec/raw';
+import type { ResourceType } from '@warp-drive/core-types/symbols';
 
 import type { Cache, CacheV1 } from '../-types/q/cache';
 import type { CacheCapabilitiesManager } from '../-types/q/cache-store-wrapper';
@@ -64,10 +66,26 @@ type CompatStore = Store & {
 };
 function upgradeStore(store: Store): asserts store is CompatStore {}
 
-export interface CreateRecordProperties {
-  id?: string | null;
-  [key: string]: unknown;
-}
+type MaybeHasId = { id?: string };
+/**
+ * Currently only records that extend object can be created via
+ * store.createRecord. This is a limitation of the current API,
+ * but can be worked around by creating a new identifier, running
+ * the cache.clientDidCreate method, and then peeking the record
+ * for the identifier.
+ *
+ * To assign primary key to a record during creation, only `id` will
+ * work correctly for `store.createRecord`, other primary key may be
+ * handled by updating the record after creation or using the flow
+ * described above.
+ *
+ * TODO: These are limitations we want to (and can) address. If you
+ * have need of lifting these limitations, please open an issue.
+ *
+ * @typedoc
+ */
+export type CreateRecordProperties<T extends MaybeHasId = MaybeHasId & Record<string, unknown>> =
+  T extends TypedRecordInstance ? Partial<Omit<T, typeof ResourceType>> : MaybeHasId & Record<string, unknown>;
 
 /**
  * A Store coordinates interaction between your application, a [Cache](https://api.emberjs.com/ember-data/release/classes/%3CInterface%3E%20Cache),
@@ -672,7 +690,9 @@ class Store extends EmberObject {
       newly created record.
     @return {Model} record
   */
-  createRecord(modelName: string, inputProperties: CreateRecordProperties): RecordInstance {
+  createRecord<T extends MaybeHasId>(modelName: TypeFromInstance<T>, inputProperties: CreateRecordProperties<T>): T;
+  createRecord(modelName: string, inputProperties: CreateRecordProperties): unknown;
+  createRecord(modelName: string, inputProperties: CreateRecordProperties): unknown {
     if (DEBUG) {
       assertDestroyingStore(this, 'createRecord');
     }
@@ -696,21 +716,22 @@ class Store extends EmberObject {
       // give the adapter an opportunity to generate one. Typically,
       // client-side ID generators will use something like uuid.js
       // to avoid conflicts.
+      let id: string | null = null;
 
       if (properties.id === null || properties.id === undefined) {
         upgradeStore(this);
         const adapter = this.adapterFor?.(modelName, true);
 
         if (adapter && adapter.generateIdForRecord) {
-          properties.id = adapter.generateIdForRecord(this, modelName, properties);
+          id = properties.id = coerceId(adapter.generateIdForRecord(this, modelName, properties));
         } else {
-          properties.id = null;
+          id = properties.id = null;
         }
+      } else {
+        id = properties.id = coerceId(properties.id);
       }
 
-      // Coerce ID to a string
-      properties.id = coerceId(properties.id);
-      const resource = { type: normalizedModelName, id: properties.id };
+      const resource = { type: normalizedModelName, id };
 
       if (resource.id) {
         const identifier = this.identifierCache.peekRecordIdentifier(resource as ResourceIdentifierObject);
@@ -749,7 +770,7 @@ class Store extends EmberObject {
     @public
     @param {Model} record
   */
-  deleteRecord(record: RecordInstance): void {
+  deleteRecord<T>(record: T): void {
     if (DEBUG) {
       assertDestroyingStore(this, 'deleteRecord');
     }
@@ -782,7 +803,7 @@ class Store extends EmberObject {
     @public
     @param {Model} record
   */
-  unloadRecord(record: RecordInstance): void {
+  unloadRecord<T>(record: T): void {
     if (DEBUG) {
       assertDestroyingStore(this, 'unloadRecord');
     }
@@ -1163,13 +1184,15 @@ class Store extends EmberObject {
     @param {Object} [options] - if the first param is a string this will be the optional options for the request. See examples for available options.
     @return {Promise} promise
   */
-  findRecord(resource: string, id: string | number, options?: FindOptions): Promise<RecordInstance>;
-  findRecord(resource: ResourceIdentifierObject, id?: FindOptions): Promise<RecordInstance>;
+  findRecord<T>(resource: TypeFromInstance<T>, id: string | number, options?: FindOptions): Promise<T>;
+  findRecord(resource: string, id: string | number, options?: FindOptions): Promise<unknown>;
+  findRecord<T>(resource: ResourceIdentifierObject<TypeFromInstance<T>>, id?: FindOptions): Promise<T>;
+  findRecord(resource: ResourceIdentifierObject, id?: FindOptions): Promise<unknown>;
   findRecord(
     resource: string | ResourceIdentifierObject,
     id?: string | number | FindOptions,
     options?: FindOptions
-  ): Promise<RecordInstance> {
+  ): Promise<unknown> {
     if (DEBUG) {
       assertDestroyingStore(this, 'findRecord');
     }

packages/store/src/-private/utils/coerce-id.ts

@@ -14,7 +14,7 @@ import { DEPRECATE_NON_STRICT_ID } from '@ember-data/deprecations';
 // corresponding record, we will not know if it is a string or a number.
 type Coercable = string | number | boolean | null | undefined | symbol;
 
-function coerceId(id: Coercable): string | null {
+function coerceId(id: unknown): string | null {
   if (DEPRECATE_NON_STRICT_ID) {
     let normalized: string | null;
     if (id === null || id === undefined || id === '') {