Add @ember-data/legacy-compat/builders (#9319)

* Add legacy-compat/builders findRecord

* Add findRecord docs

* Add legacy-compat/builders query

* Add query docs

* queryRecord

* findAll

* saveRecord

* saveRecord tests

* Docs pass

* Fix test:docs

* Fix lint

* Remove outdated TODO

* Deprecate

* Fix test

* Don't export options and return types

* Move @deprecated under @method

* Make builder return types generic

* Remove Ember references from docs

packages/legacy-compat/.eslintrc.cjs

@@ -16,7 +16,7 @@ const config = {
     base.rules(),
     imports.rules(),
     isolation.rules({
-      allowedImports: ['@ember/debug', '@ember/application'],
+      allowedImports: ['@ember/debug', '@ember/string', '@ember/application'],
     }),
     {}
   ),

packages/legacy-compat/package.json

@@ -94,6 +94,7 @@
     "@ember-data/json-api": "workspace:5.4.0-alpha.52",
     "@ember-data/request": "workspace:5.4.0-alpha.52",
     "@ember-data/store": "workspace:5.4.0-alpha.52",
+    "@ember/string": "^3.1.1",
     "@warp-drive/core-types": "workspace:0.0.0-alpha.38"
   },
   "peerDependenciesMeta": {

packages/legacy-compat/rollup.config.mjs

@@ -19,7 +19,7 @@ export default {
   plugins: [
     // These are the modules that users should be able to import from your
     // addon. Anything not listed here may get optimized away.
-    addon.publicEntrypoints(['index.js', '-private.js']),
+    addon.publicEntrypoints(['index.js', 'builders.js', '-private.js']),
 
     nodeResolve({ extensions: ['.ts'] }),
     babel({

packages/legacy-compat/src/builders.ts

@@ -0,0 +1,19 @@
+/**
+  Builders for migrating from `store` methods to `store.request`.
+
+  These builders enable you to migrate your codebase to using the correct syntax for `store.request` while temporarily preserving legacy behaviors.
+  This is useful for quickly upgrading an entire app to a unified syntax while a longer incremental migration is made to shift off of adapters and serializers.
+  To that end, these builders are deprecated and will be removed in a future version of Ember Data.
+
+  @module @ember-data/legacy-compat/builders
+  @main @ember-data/legacy-compat/builders
+  @deprecated
+*/
+
+export { findAllBuilder as findAll } from './builders/find-all';
+
+export { findRecordBuilder as findRecord } from './builders/find-record';
+
+export { queryBuilder as query, queryRecordBuilder as queryRecord } from './builders/query';
+
+export { saveRecordBuilder as saveRecord } from './builders/save-record';

packages/legacy-compat/src/builders/find-all.ts

@@ -0,0 +1,62 @@
+/**
+ * @module @ember-data/legacy-compat/builders
+ */
+import { assert } from '@ember/debug';
+
+import type { StoreRequestInput } from '@ember-data/store';
+import type { FindAllOptions } from '@ember-data/store/-types/q/store';
+import type { TypedRecordInstance, TypeFromInstance } from '@warp-drive/core-types/record';
+import { SkipCache } from '@warp-drive/core-types/request';
+
+import { normalizeModelName } from './utils';
+
+type FindAllRequestInput<T extends string> = StoreRequestInput & {
+  op: 'findAll';
+  data: {
+    type: T;
+    options: FindAllBuilderOptions;
+  };
+};
+
+type FindAllBuilderOptions = FindAllOptions;
+
+/**
+  This function builds a request config to perform a `findAll` request for the given type.
+  When passed to `store.request`, this config will result in the same behavior as a `store.findAll` request.
+  Additionally, it takes the same options as `store.findAll`.
+
+  All `@ember-data/legacy-compat` builders exist to enable you to migrate your codebase to using the correct syntax for `store.request` while temporarily preserving legacy behaviors.
+  This is useful for quickly upgrading an entire app to a unified syntax while a longer incremental migration is made to shift off of adapters and serializers.
+  To that end, these builders are deprecated and will be removed in a future version of Ember Data.
+
+  @method findAll
+  @deprecated
+  @public
+  @static
+  @for @ember-data/legacy-compat/builders
+  @param {string} type the name of the resource
+  @param {object} query a query to be used by the adapter
+  @param {FindAllBuilderOptions} [options] optional, may include `adapterOptions` hash which will be passed to adapter.findAll
+  @return {FindAllRequestInput} request config
+*/
+export function findAllBuilder<T extends TypedRecordInstance>(
+  type: TypeFromInstance<T>,
+  options?: FindAllBuilderOptions
+): FindAllRequestInput<TypeFromInstance<T>>;
+export function findAllBuilder(type: string, options?: FindAllBuilderOptions): FindAllRequestInput<string>;
+export function findAllBuilder(type: string, options: FindAllBuilderOptions = {}): FindAllRequestInput<string> {
+  assert(`You need to pass a model name to the findAll builder`, type);
+  assert(
+    `Model name passed to the findAll builder must be a dasherized string instead of ${type}`,
+    typeof type === 'string'
+  );
+
+  return {
+    op: 'findAll',
+    data: {
+      type: normalizeModelName(type),
+      options: options || {},
+    },
+    cacheOptions: { [SkipCache as symbol]: true },
+  };
+}

packages/legacy-compat/src/builders/find-record.ts

@@ -0,0 +1,113 @@
+/**
+ * @module @ember-data/legacy-compat/builders
+ */
+import { assert } from '@ember/debug';
+
+import type { StoreRequestInput } from '@ember-data/store';
+import { constructResource, ensureStringId } from '@ember-data/store/-private';
+import type { BaseFinderOptions, FindRecordOptions } from '@ember-data/store/-types/q/store';
+import type { TypedRecordInstance, TypeFromInstance } from '@warp-drive/core-types/record';
+import { SkipCache } from '@warp-drive/core-types/request';
+import type { ResourceIdentifierObject } from '@warp-drive/core-types/spec/raw';
+
+import { isMaybeIdentifier, normalizeModelName } from './utils';
+
+type FindRecordRequestInput<T extends string> = StoreRequestInput & {
+  op: 'findRecord';
+  data: {
+    record: ResourceIdentifierObject<T>;
+    options: FindRecordBuilderOptions;
+  };
+};
+
+type FindRecordBuilderOptions = Omit<FindRecordOptions, 'preload'>;
+
+/**
+  This function builds a request config to find the record for a given identifier or type and id combination.
+  When passed to `store.request`, this config will result in the same behavior as a `store.findRecord` request.
+  Additionally, it takes the same options as `store.findRecord`, with the exception of `preload` (which is unsupported).
+
+  **Example 1**
+
+  ```ts
+  import { findRecord } from '@ember-data/legacy-compat/builders';
+  const { content: post } = await store.request<Post>(findRecord<Post>('post', '1'));
+  ```
+
+  **Example 2**
+
+  `findRecord` can be called with a single identifier argument instead of the combination
+  of `type` (modelName) and `id` as separate arguments. You may recognize this combo as
+  the typical pairing from [JSON:API](https://jsonapi.org/format/#document-resource-object-identification)
+
+  ```ts
+  import { findRecord } from '@ember-data/legacy-compat/builders';
+  const { content: post } = await store.request<Post>(findRecord<Post>({ type: 'post', id }));
+  ```
+
+  All `@ember-data/legacy-compat` builders exist to enable you to migrate your codebase to using the correct syntax for `store.request` while temporarily preserving legacy behaviors.
+  This is useful for quickly upgrading an entire app to a unified syntax while a longer incremental migration is made to shift off of adapters and serializers.
+  To that end, these builders are deprecated and will be removed in a future version of Ember Data.
+
+  @method findRecord
+  @deprecated
+  @public
+  @static
+  @for @ember-data/legacy-compat/builders
+  @param {string|object} type - either a string representing the name of the resource or a ResourceIdentifier object containing both the type (a string) and the id (a string) for the record or an lid (a string) of an existing record
+  @param {string|number|object} id - optional object with options for the request only if the first param is a ResourceIdentifier, else the string id of the record to be retrieved
+  @param {FindRecordBuilderOptions} [options] - if the first param is a string this will be the optional options for the request. See examples for available options.
+  @return {FindRecordRequestInput} request config
+*/
+export function findRecordBuilder<T extends TypedRecordInstance>(
+  resource: TypeFromInstance<T>,
+  id: string,
+  options?: FindRecordBuilderOptions
+): FindRecordRequestInput<TypeFromInstance<T>>;
+export function findRecordBuilder(
+  resource: string,
+  id: string,
+  options?: FindRecordBuilderOptions
+): FindRecordRequestInput<string>;
+export function findRecordBuilder<T extends TypedRecordInstance>(
+  resource: ResourceIdentifierObject<TypeFromInstance<T>>,
+  options?: FindRecordBuilderOptions
+): FindRecordRequestInput<TypeFromInstance<T>>;
+export function findRecordBuilder(
+  resource: ResourceIdentifierObject,
+  options?: FindRecordBuilderOptions
+): FindRecordRequestInput<string>;
+export function findRecordBuilder(
+  resource: string | ResourceIdentifierObject,
+  idOrOptions?: string | FindRecordBuilderOptions,
+  options?: FindRecordBuilderOptions
+): FindRecordRequestInput<string> {
+  assert(
+    `You need to pass a modelName or resource identifier as the first argument to the findRecord builder`,
+    resource
+  );
+  if (isMaybeIdentifier(resource)) {
+    options = idOrOptions as BaseFinderOptions | undefined;
+  } else {
+    assert(
+      `You need to pass a modelName or resource identifier as the first argument to the findRecord builder (passed ${resource})`,
+      typeof resource === 'string'
+    );
+    const type = normalizeModelName(resource);
+    const normalizedId = ensureStringId(idOrOptions as string | number);
+    resource = constructResource(type, normalizedId);
+  }
+
+  options = options || {};
+
+  assert('findRecord builder does not support options.preload', !(options as FindRecordOptions).preload);
+
+  return {
+    op: 'findRecord' as const,
+    data: {
+      record: resource,
+      options,
+    },
+    cacheOptions: { [SkipCache as symbol]: true },
+  };
+}

packages/legacy-compat/src/builders/query.ts

@@ -0,0 +1,135 @@
+/**
+ * @module @ember-data/legacy-compat/builders
+ */
+import { assert } from '@ember/debug';
+
+import type { StoreRequestInput } from '@ember-data/store';
+import type { QueryOptions } from '@ember-data/store/-types/q/store';
+import type { TypedRecordInstance, TypeFromInstance } from '@warp-drive/core-types/record';
+import { SkipCache } from '@warp-drive/core-types/request';
+
+import { normalizeModelName } from './utils';
+
+type QueryRequestInput<T extends string> = StoreRequestInput & {
+  op: 'query';
+  data: {
+    type: T;
+    query: Record<string, unknown>;
+    options: QueryBuilderOptions;
+  };
+};
+
+type QueryBuilderOptions = QueryOptions;
+
+/**
+  This function builds a request config for a given type and query object.
+  When passed to `store.request`, this config will result in the same behavior as a `store.query` request.
+  Additionally, it takes the same options as `store.query`.
+
+  All `@ember-data/legacy-compat` builders exist to enable you to migrate your codebase to using the correct syntax for `store.request` while temporarily preserving legacy behaviors.
+  This is useful for quickly upgrading an entire app to a unified syntax while a longer incremental migration is made to shift off of adapters and serializers.
+  To that end, these builders are deprecated and will be removed in a future version of Ember Data.
+
+  @method query
+  @deprecated
+  @public
+  @static
+  @for @ember-data/legacy-compat/builders
+  @param {string} type the name of the resource
+  @param {object} query a query to be used by the adapter
+  @param {QueryBuilderOptions} [options] optional, may include `adapterOptions` hash which will be passed to adapter.query
+  @return {QueryRequestInput} request config
+*/
+export function queryBuilder<T extends TypedRecordInstance>(
+  type: TypeFromInstance<T>,
+  query: Record<string, unknown>,
+  options?: QueryBuilderOptions
+): QueryRequestInput<TypeFromInstance<T>>;
+export function queryBuilder(
+  type: string,
+  query: Record<string, unknown>,
+  options?: QueryBuilderOptions
+): QueryRequestInput<string>;
+export function queryBuilder(
+  type: string,
+  query: Record<string, unknown>,
+  options: QueryBuilderOptions = {}
+): QueryRequestInput<string> {
+  assert(`You need to pass a model name to the query builder`, type);
+  assert(`You need to pass a query hash to the query builder`, query);
+  assert(
+    `Model name passed to the query builder must be a dasherized string instead of ${type}`,
+    typeof type === 'string'
+  );
+
+  return {
+    op: 'query' as const,
+    data: {
+      type: normalizeModelName(type),
+      query,
+      options: options,
+    },
+    cacheOptions: { [SkipCache as symbol]: true },
+  };
+}
+
+type QueryRecordRequestInput<T extends string> = StoreRequestInput & {
+  op: 'queryRecord';
+  data: {
+    type: T;
+    query: Record<string, unknown>;
+    options: QueryBuilderOptions;
+  };
+};
+
+/**
+  This function builds a request config for a given type and query object.
+  When passed to `store.request`, this config will result in the same behavior as a `store.queryRecord` request.
+  Additionally, it takes the same options as `store.queryRecord`.
+
+  All `@ember-data/legacy-compat` builders exist to enable you to migrate your codebase to using the correct syntax for `store.request` while temporarily preserving legacy behaviors.
+  This is useful for quickly upgrading an entire app to a unified syntax while a longer incremental migration is made to shift off of adapters and serializers.
+  To that end, these builders are deprecated and will be removed in a future version of Ember Data.
+
+  @method queryRecord
+  @deprecated
+  @public
+  @static
+  @for @ember-data/legacy-compat/builders
+  @param {string} type the name of the resource
+  @param {object} query a query to be used by the adapter
+  @param {QueryBuilderOptions} [options] optional, may include `adapterOptions` hash which will be passed to adapter.query
+  @return {QueryRecordRequestInput} request config
+*/
+export function queryRecordBuilder<T extends TypedRecordInstance>(
+  type: TypeFromInstance<T>,
+  query: Record<string, unknown>,
+  options?: QueryBuilderOptions
+): QueryRecordRequestInput<TypeFromInstance<T>>;
+export function queryRecordBuilder(
+  type: string,
+  query: Record<string, unknown>,
+  options?: QueryBuilderOptions
+): QueryRecordRequestInput<string>;
+export function queryRecordBuilder(
+  type: string,
+  query: Record<string, unknown>,
+  options?: QueryBuilderOptions
+): QueryRecordRequestInput<string> {
+  assert(`You need to pass a model name to the queryRecord builder`, type);
+  assert(`You need to pass a query hash to the queryRecord builder`, query);
+  assert(
+    `Model name passed to the queryRecord builder must be a dasherized string instead of ${type}`,
+    typeof type === 'string'
+  );
+
+  return {
+    op: 'queryRecord',
+    data: {
+      type: normalizeModelName(type),
+      query,
+      options: options || {},
+    },
+    cacheOptions: { [SkipCache as symbol]: true },
+  };
+}