Skip to content

Commit 286f5bc

Browse files
gitKrystangitKrystan
authored
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
1 parent ed52aa2 commit 286f5bc

File tree

20 files changed

+1184
-15
lines changed

20 files changed

+1184
-15
lines changed

‎packages/legacy-compat/.eslintrc.cjs

+1-1
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ const config = {
1616
base.rules(),
1717
imports.rules(),
1818
isolation.rules({
19-
allowedImports: ['@ember/debug', '@ember/application'],
19+
allowedImports: ['@ember/debug', '@ember/string', '@ember/application'],
2020
}),
2121
{}
2222
),

‎packages/legacy-compat/package.json

+1
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,7 @@
9494
"@ember-data/json-api": "workspace:5.4.0-alpha.52",
9595
"@ember-data/request": "workspace:5.4.0-alpha.52",
9696
"@ember-data/store": "workspace:5.4.0-alpha.52",
97+
"@ember/string": "^3.1.1",
9798
"@warp-drive/core-types": "workspace:0.0.0-alpha.38"
9899
},
99100
"peerDependenciesMeta": {

‎packages/legacy-compat/rollup.config.mjs

+1-1
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ export default {
1919
plugins: [
2020
// These are the modules that users should be able to import from your
2121
// addon. Anything not listed here may get optimized away.
22-
addon.publicEntrypoints(['index.js', '-private.js']),
22+
addon.publicEntrypoints(['index.js', 'builders.js', '-private.js']),
2323

2424
nodeResolve({ extensions: ['.ts'] }),
2525
babel({

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

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
/**
2+
Builders for migrating from `store` methods to `store.request`.
3+
4+
These builders enable you to migrate your codebase to using the correct syntax for `store.request` while temporarily preserving legacy behaviors.
5+
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.
6+
To that end, these builders are deprecated and will be removed in a future version of Ember Data.
7+
8+
@module @ember-data/legacy-compat/builders
9+
@main @ember-data/legacy-compat/builders
10+
@deprecated
11+
*/
12+
13+
export { findAllBuilder as findAll } from './builders/find-all';
14+
15+
export { findRecordBuilder as findRecord } from './builders/find-record';
16+
17+
export { queryBuilder as query, queryRecordBuilder as queryRecord } from './builders/query';
18+
19+
export { saveRecordBuilder as saveRecord } from './builders/save-record';

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

+62
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
/**
2+
* @module @ember-data/legacy-compat/builders
3+
*/
4+
import { assert } from '@ember/debug';
5+
6+
import type { StoreRequestInput } from '@ember-data/store';
7+
import type { FindAllOptions } from '@ember-data/store/-types/q/store';
8+
import type { TypedRecordInstance, TypeFromInstance } from '@warp-drive/core-types/record';
9+
import { SkipCache } from '@warp-drive/core-types/request';
10+
11+
import { normalizeModelName } from './utils';
12+
13+
type FindAllRequestInput<T extends string> = StoreRequestInput & {
14+
op: 'findAll';
15+
data: {
16+
type: T;
17+
options: FindAllBuilderOptions;
18+
};
19+
};
20+
21+
type FindAllBuilderOptions = FindAllOptions;
22+
23+
/**
24+
This function builds a request config to perform a `findAll` request for the given type.
25+
When passed to `store.request`, this config will result in the same behavior as a `store.findAll` request.
26+
Additionally, it takes the same options as `store.findAll`.
27+
28+
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.
29+
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.
30+
To that end, these builders are deprecated and will be removed in a future version of Ember Data.
31+
32+
@method findAll
33+
@deprecated
34+
@public
35+
@static
36+
@for @ember-data/legacy-compat/builders
37+
@param {string} type the name of the resource
38+
@param {object} query a query to be used by the adapter
39+
@param {FindAllBuilderOptions} [options] optional, may include `adapterOptions` hash which will be passed to adapter.findAll
40+
@return {FindAllRequestInput} request config
41+
*/
42+
export function findAllBuilder<T extends TypedRecordInstance>(
43+
type: TypeFromInstance<T>,
44+
options?: FindAllBuilderOptions
45+
): FindAllRequestInput<TypeFromInstance<T>>;
46+
export function findAllBuilder(type: string, options?: FindAllBuilderOptions): FindAllRequestInput<string>;
47+
export function findAllBuilder(type: string, options: FindAllBuilderOptions = {}): FindAllRequestInput<string> {
48+
assert(`You need to pass a model name to the findAll builder`, type);
49+
assert(
50+
`Model name passed to the findAll builder must be a dasherized string instead of ${type}`,
51+
typeof type === 'string'
52+
);
53+
54+
return {
55+
op: 'findAll',
56+
data: {
57+
type: normalizeModelName(type),
58+
options: options || {},
59+
},
60+
cacheOptions: { [SkipCache as symbol]: true },
61+
};
62+
}

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

+113
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
/**
2+
* @module @ember-data/legacy-compat/builders
3+
*/
4+
import { assert } from '@ember/debug';
5+
6+
import type { StoreRequestInput } from '@ember-data/store';
7+
import { constructResource, ensureStringId } from '@ember-data/store/-private';
8+
import type { BaseFinderOptions, FindRecordOptions } from '@ember-data/store/-types/q/store';
9+
import type { TypedRecordInstance, TypeFromInstance } from '@warp-drive/core-types/record';
10+
import { SkipCache } from '@warp-drive/core-types/request';
11+
import type { ResourceIdentifierObject } from '@warp-drive/core-types/spec/raw';
12+
13+
import { isMaybeIdentifier, normalizeModelName } from './utils';
14+
15+
type FindRecordRequestInput<T extends string> = StoreRequestInput & {
16+
op: 'findRecord';
17+
data: {
18+
record: ResourceIdentifierObject<T>;
19+
options: FindRecordBuilderOptions;
20+
};
21+
};
22+
23+
type FindRecordBuilderOptions = Omit<FindRecordOptions, 'preload'>;
24+
25+
/**
26+
This function builds a request config to find the record for a given identifier or type and id combination.
27+
When passed to `store.request`, this config will result in the same behavior as a `store.findRecord` request.
28+
Additionally, it takes the same options as `store.findRecord`, with the exception of `preload` (which is unsupported).
29+
30+
**Example 1**
31+
32+
```ts
33+
import { findRecord } from '@ember-data/legacy-compat/builders';
34+
const { content: post } = await store.request<Post>(findRecord<Post>('post', '1'));
35+
```
36+
37+
**Example 2**
38+
39+
`findRecord` can be called with a single identifier argument instead of the combination
40+
of `type` (modelName) and `id` as separate arguments. You may recognize this combo as
41+
the typical pairing from [JSON:API](https://jsonapi.org/format/#document-resource-object-identification)
42+
43+
```ts
44+
import { findRecord } from '@ember-data/legacy-compat/builders';
45+
const { content: post } = await store.request<Post>(findRecord<Post>({ type: 'post', id }));
46+
```
47+
48+
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.
49+
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.
50+
To that end, these builders are deprecated and will be removed in a future version of Ember Data.
51+
52+
@method findRecord
53+
@deprecated
54+
@public
55+
@static
56+
@for @ember-data/legacy-compat/builders
57+
@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
58+
@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
59+
@param {FindRecordBuilderOptions} [options] - if the first param is a string this will be the optional options for the request. See examples for available options.
60+
@return {FindRecordRequestInput} request config
61+
*/
62+
export function findRecordBuilder<T extends TypedRecordInstance>(
63+
resource: TypeFromInstance<T>,
64+
id: string,
65+
options?: FindRecordBuilderOptions
66+
): FindRecordRequestInput<TypeFromInstance<T>>;
67+
export function findRecordBuilder(
68+
resource: string,
69+
id: string,
70+
options?: FindRecordBuilderOptions
71+
): FindRecordRequestInput<string>;
72+
export function findRecordBuilder<T extends TypedRecordInstance>(
73+
resource: ResourceIdentifierObject<TypeFromInstance<T>>,
74+
options?: FindRecordBuilderOptions
75+
): FindRecordRequestInput<TypeFromInstance<T>>;
76+
export function findRecordBuilder(
77+
resource: ResourceIdentifierObject,
78+
options?: FindRecordBuilderOptions
79+
): FindRecordRequestInput<string>;
80+
export function findRecordBuilder(
81+
resource: string | ResourceIdentifierObject,
82+
idOrOptions?: string | FindRecordBuilderOptions,
83+
options?: FindRecordBuilderOptions
84+
): FindRecordRequestInput<string> {
85+
assert(
86+
`You need to pass a modelName or resource identifier as the first argument to the findRecord builder`,
87+
resource
88+
);
89+
if (isMaybeIdentifier(resource)) {
90+
options = idOrOptions as BaseFinderOptions | undefined;
91+
} else {
92+
assert(
93+
`You need to pass a modelName or resource identifier as the first argument to the findRecord builder (passed ${resource})`,
94+
typeof resource === 'string'
95+
);
96+
const type = normalizeModelName(resource);
97+
const normalizedId = ensureStringId(idOrOptions as string | number);
98+
resource = constructResource(type, normalizedId);
99+
}
100+
101+
options = options || {};
102+
103+
assert('findRecord builder does not support options.preload', !(options as FindRecordOptions).preload);
104+
105+
return {
106+
op: 'findRecord' as const,
107+
data: {
108+
record: resource,
109+
options,
110+
},
111+
cacheOptions: { [SkipCache as symbol]: true },
112+
};
113+
}

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

+135
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
/**
2+
* @module @ember-data/legacy-compat/builders
3+
*/
4+
import { assert } from '@ember/debug';
5+
6+
import type { StoreRequestInput } from '@ember-data/store';
7+
import type { QueryOptions } from '@ember-data/store/-types/q/store';
8+
import type { TypedRecordInstance, TypeFromInstance } from '@warp-drive/core-types/record';
9+
import { SkipCache } from '@warp-drive/core-types/request';
10+
11+
import { normalizeModelName } from './utils';
12+
13+
type QueryRequestInput<T extends string> = StoreRequestInput & {
14+
op: 'query';
15+
data: {
16+
type: T;
17+
query: Record<string, unknown>;
18+
options: QueryBuilderOptions;
19+
};
20+
};
21+
22+
type QueryBuilderOptions = QueryOptions;
23+
24+
/**
25+
This function builds a request config for a given type and query object.
26+
When passed to `store.request`, this config will result in the same behavior as a `store.query` request.
27+
Additionally, it takes the same options as `store.query`.
28+
29+
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.
30+
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.
31+
To that end, these builders are deprecated and will be removed in a future version of Ember Data.
32+
33+
@method query
34+
@deprecated
35+
@public
36+
@static
37+
@for @ember-data/legacy-compat/builders
38+
@param {string} type the name of the resource
39+
@param {object} query a query to be used by the adapter
40+
@param {QueryBuilderOptions} [options] optional, may include `adapterOptions` hash which will be passed to adapter.query
41+
@return {QueryRequestInput} request config
42+
*/
43+
export function queryBuilder<T extends TypedRecordInstance>(
44+
type: TypeFromInstance<T>,
45+
query: Record<string, unknown>,
46+
options?: QueryBuilderOptions
47+
): QueryRequestInput<TypeFromInstance<T>>;
48+
export function queryBuilder(
49+
type: string,
50+
query: Record<string, unknown>,
51+
options?: QueryBuilderOptions
52+
): QueryRequestInput<string>;
53+
export function queryBuilder(
54+
type: string,
55+
query: Record<string, unknown>,
56+
options: QueryBuilderOptions = {}
57+
): QueryRequestInput<string> {
58+
assert(`You need to pass a model name to the query builder`, type);
59+
assert(`You need to pass a query hash to the query builder`, query);
60+
assert(
61+
`Model name passed to the query builder must be a dasherized string instead of ${type}`,
62+
typeof type === 'string'
63+
);
64+
65+
return {
66+
op: 'query' as const,
67+
data: {
68+
type: normalizeModelName(type),
69+
query,
70+
options: options,
71+
},
72+
cacheOptions: { [SkipCache as symbol]: true },
73+
};
74+
}
75+
76+
type QueryRecordRequestInput<T extends string> = StoreRequestInput & {
77+
op: 'queryRecord';
78+
data: {
79+
type: T;
80+
query: Record<string, unknown>;
81+
options: QueryBuilderOptions;
82+
};
83+
};
84+
85+
/**
86+
This function builds a request config for a given type and query object.
87+
When passed to `store.request`, this config will result in the same behavior as a `store.queryRecord` request.
88+
Additionally, it takes the same options as `store.queryRecord`.
89+
90+
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.
91+
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.
92+
To that end, these builders are deprecated and will be removed in a future version of Ember Data.
93+
94+
@method queryRecord
95+
@deprecated
96+
@public
97+
@static
98+
@for @ember-data/legacy-compat/builders
99+
@param {string} type the name of the resource
100+
@param {object} query a query to be used by the adapter
101+
@param {QueryBuilderOptions} [options] optional, may include `adapterOptions` hash which will be passed to adapter.query
102+
@return {QueryRecordRequestInput} request config
103+
*/
104+
export function queryRecordBuilder<T extends TypedRecordInstance>(
105+
type: TypeFromInstance<T>,
106+
query: Record<string, unknown>,
107+
options?: QueryBuilderOptions
108+
): QueryRecordRequestInput<TypeFromInstance<T>>;
109+
export function queryRecordBuilder(
110+
type: string,
111+
query: Record<string, unknown>,
112+
options?: QueryBuilderOptions
113+
): QueryRecordRequestInput<string>;
114+
export function queryRecordBuilder(
115+
type: string,
116+
query: Record<string, unknown>,
117+
options?: QueryBuilderOptions
118+
): QueryRecordRequestInput<string> {
119+
assert(`You need to pass a model name to the queryRecord builder`, type);
120+
assert(`You need to pass a query hash to the queryRecord builder`, query);
121+
assert(
122+
`Model name passed to the queryRecord builder must be a dasherized string instead of ${type}`,
123+
typeof type === 'string'
124+
);
125+
126+
return {
127+
op: 'queryRecord',
128+
data: {
129+
type: normalizeModelName(type),
130+
query,
131+
options: options || {},
132+
},
133+
cacheOptions: { [SkipCache as symbol]: true },
134+
};
135+
}

0 commit comments

Comments
 (0)