diff --git a/.eslintignore b/.eslintignore index 8bd28fcc869..ff6d2c29038 100644 --- a/.eslintignore +++ b/.eslintignore @@ -3,6 +3,7 @@ packages/*/blueprints/*/*files/ vendor/ # compiled output +/packages/-ember-data/docs/ dist tmp @@ -13,6 +14,7 @@ node_modules # misc /coverage/ !.* +/.yarn/ # ember-try .node_modules.ember-try diff --git a/.eslintrc.js b/.eslintrc.js index ade3af92929..77ccfa11673 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -31,6 +31,11 @@ module.exports = { 'no-irregular-whitespace': 'error', 'no-undef': 'error', 'no-eq-null': 'error', + 'no-console': 'error', // no longer recommended in eslint v6, this restores it + + // Too many false positives + // See https://github.com/eslint/eslint/issues/11899 and similar + 'require-atomic-updates': 'off', }, globals: { heimdall: true, @@ -48,7 +53,7 @@ module.exports = { '.mocharc.js', '.eslintrc.js', '.prettierrc.js', - 'bin/*.js', + 'bin/*', 'packages/-build-infra/src/**/*.js', 'packages/-test-infra/src/**/*.js', 'packages/*/ember-cli-build.js', @@ -87,5 +92,26 @@ module.exports = { mocha: true, }, }, + { + files: ['packages/-ember-data/node-tests/docs/*.js'], + + env: { + qunit: true, + es6: false, + }, + }, + + // bin files + { + files: ['bin/*'], + // eslint-disable-next-line node/no-unpublished-require + rules: Object.assign({}, require('eslint-plugin-node').configs.recommended.rules, { + 'no-console': 'off', + 'no-process-exit': 'off', + 'node/no-extraneous-require': 'off', + 'node/no-unpublished-require': 'off', + 'node/shebang': 'off', + }), + }, ], }; diff --git a/CHANGELOG.md b/CHANGELOG.md index 7275683ff92..bf4a5c87b28 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1863,7 +1863,7 @@ post.constructor.typeKey => postSnapshot.typeKey If you need to access the underlying record of a snapshot you can do so by accessing `snapshot.record`. -The full API reference of `DS.Snapshot` can be found [here](https://emberjs.com/api/data/classes/DS.Snapshot.html). +The full API reference of `DS.Snapshot` can be found [here](https://api.emberjs.com/ember-data/release/classes/Snapshot). #### Changes @@ -2097,7 +2097,7 @@ to set metadata. ##### `ManyArray`s are no longer `RecordArray`s -[ManyArray](https://emberjs.com/api/data/classes/DS.ManyArray.html), +[ManyArray](https://api.emberjs.com/ember-data/release/classes/ManyArray), the object Ember Data uses to represent `DS.hasMany` relationships has been changed so it no longer extends from `RecordArray`. This means if you were relying on the RecordArray's `content` property to access the diff --git a/bin/publish.js b/bin/publish.js index ebcf932b4aa..d146728fd90 100644 --- a/bin/publish.js +++ b/bin/publish.js @@ -142,11 +142,7 @@ function assertGitIsClean() { } let expectedChannelBranch = - options.distTag === 'canary' - ? 'master' - : options.distTag === 'latest' - ? 'release' - : options.distTag; + options.distTag === 'canary' ? 'master' : options.distTag === 'latest' ? 'release' : options.distTag; if (options.channel === 'lts') { expectedChannelBranch = `lts-${semver.major(options.currentVersion)}-${semver.minor(options.currentVersion)}`; diff --git a/packages/-ember-data/addon/-private/core.js b/packages/-ember-data/addon/-private/core.js index 4e81db312a2..bd88f3bf3b0 100644 --- a/packages/-ember-data/addon/-private/core.js +++ b/packages/-ember-data/addon/-private/core.js @@ -1,30 +1,26 @@ +/** + @module @ember-data + @main @ember-data + */ + import Namespace from '@ember/application/namespace'; import Ember from 'ember'; import VERSION from 'ember-data/version'; /** - @module ember-data -*/ - -/** - All Ember Data classes, methods and functions are defined inside of this namespace. - - @class DS - @static -*/ + * @property VERSION + * @public + * @static + * @for @ember-data + */ -/** - @property VERSION - @type String - @static -*/ const DS = Namespace.create({ VERSION: VERSION, name: 'DS', }); if (Ember.libraries) { - Ember.libraries.registerCoreLibrary('Ember Data', DS.VERSION); + Ember.libraries.registerCoreLibrary('Ember Data', VERSION); } export default DS; diff --git a/packages/-ember-data/addon/-private/system/debug/debug-adapter.js b/packages/-ember-data/addon/-private/system/debug/debug-adapter.js index 5bd017a3666..41d6152197c 100644 --- a/packages/-ember-data/addon/-private/system/debug/debug-adapter.js +++ b/packages/-ember-data/addon/-private/system/debug/debug-adapter.js @@ -1,5 +1,5 @@ /** - @module ember-data + @module @ember-data/debug */ import { addObserver, removeObserver } from '@ember/object/observers'; @@ -10,11 +10,12 @@ import { assert } from '@ember/debug'; import { get } from '@ember/object'; import Model from '@ember-data/model'; -/* - Extend `Ember.DataAdapter` with ED specific code. +/** + Implements `@ember/debug/data-adapter` with for EmberData + integration with the ember-inspector. @class DebugAdapter - @extends Ember.DataAdapter + @extends DataAdapter @private */ export default DataAdapter.extend({ @@ -26,6 +27,13 @@ export default DataAdapter.extend({ ]; }, + /** + Detect whether a class is a Model + @public + @method detect + @param {Model} typeClass + @return {Boolean} Whether the typeClass is a Model class or not + */ detect(typeClass) { return typeClass !== Model && Model.detect(typeClass); }, @@ -38,6 +46,15 @@ export default DataAdapter.extend({ ); }, + /** + Get the columns for a given model type + @public + @method columnsForType + @param {Model} typeClass + @return {Array} An array of columns of the following format: + name: {String} The name of the column + desc: {String} Humanized description (what would show in a table column name) + */ columnsForType(typeClass) { let columns = [ { @@ -57,6 +74,16 @@ export default DataAdapter.extend({ return columns; }, + /** + Fetches all loaded records for a given type + @public + @method getRecords + @param {Model} modelClass of the record + @param {String} modelName of the record + @return {Array} An array of Model records + This array will be observed for changes, + so it should update when new records are added/removed + */ getRecords(modelClass, modelName) { if (arguments.length < 2) { // Legacy Ember.js < 1.13 support @@ -72,6 +99,14 @@ export default DataAdapter.extend({ return this.get('store').peekAll(modelName); }, + /** + Gets the values for each column + This is the attribute values for a given record + @public + @method getRecordColumnValues + @param {Model} record to get values from + @return {Object} Keys should match column names defined by the model type + */ getRecordColumnValues(record) { let count = 0; let columnValues = { id: get(record, 'id') }; @@ -85,6 +120,13 @@ export default DataAdapter.extend({ return columnValues; }, + /** + Returns keywords to match when searching records + @public + @method getRecordKeywords + @param {Model} record + @return {Array} Relevant keywords for search based on the record's attribute values + */ getRecordKeywords(record) { let keywords = []; let keys = A(['id']); @@ -93,6 +135,14 @@ export default DataAdapter.extend({ return keywords; }, + /** + Returns the values of filters defined by `getFilters` + These reflect the state of the record + @public + @method getRecordFilterValues + @param {Model} record + @return {Object} The record state filter values + */ getRecordFilterValues(record) { return { isNew: record.get('isNew'), @@ -101,6 +151,14 @@ export default DataAdapter.extend({ }; }, + /** + Returns a color that represents the record's state + @public + @method getRecordColor + @param {Model} record + @return {String} The record color + Possible options: black, blue, green + */ getRecordColor(record) { let color = 'black'; if (record.get('isNew')) { @@ -111,6 +169,15 @@ export default DataAdapter.extend({ return color; }, + /** + Observes all relevant properties and re-sends the wrapped record + when a change occurs + @public + @method observerRecord + @param {Model} record + @param {Function} recordUpdated Callback used to notify changes + @return {Function} The function to call to remove all observers + */ observeRecord(record, recordUpdated) { let releaseMethods = A(); let keysToObserve = A(['id', 'isNew', 'hasDirtyAttributes']); diff --git a/packages/-ember-data/addon/index.js b/packages/-ember-data/addon/index.js index e67f4150608..9ebc49be31d 100644 --- a/packages/-ember-data/addon/index.js +++ b/packages/-ember-data/addon/index.js @@ -1,12 +1,6 @@ import { VERSION } from '@ember/version'; import EmberError from '@ember/error'; -/** - Ember Data - @module ember-data - @main ember-data -*/ - if (VERSION.match(/^1\.([0-9]|1[0-2])\./)) { throw new EmberError( 'Ember Data requires at least Ember 1.13.0, but you have ' + diff --git a/packages/-ember-data/addon/relationships.js b/packages/-ember-data/addon/relationships.js index 5fe6c9ed077..c6616b398c9 100644 --- a/packages/-ember-data/addon/relationships.js +++ b/packages/-ember-data/addon/relationships.js @@ -1,4 +1 @@ -/** - @module ember-data -*/ export { belongsTo, hasMany } from '@ember-data/model'; diff --git a/packages/-ember-data/app/initializers/ember-data.js b/packages/-ember-data/app/initializers/ember-data.js index 8d185c5c98b..0b3e96c1f38 100644 --- a/packages/-ember-data/app/initializers/ember-data.js +++ b/packages/-ember-data/app/initializers/ember-data.js @@ -2,44 +2,11 @@ import setupContainer from 'ember-data/setup-container'; import 'ember-data'; /* + This code initializes EmberData in an Ember application. - This code initializes Ember-Data onto an Ember application. - - If an Ember.js developer defines a subclass of DS.Store on their application, - as `App.StoreService` (or via a module system that resolves to `service:store`) - this code will automatically instantiate it and make it available on the - router. - - Additionally, after an application's controllers have been injected, they will - each have the store made available to them. - - For example, imagine an Ember.js application with the following classes: - - ```app/services/store.js - import DS from 'ember-data'; - - export default DS.Store.extend({ - adapter: 'custom' - }); - ``` - - ```app/controllers/posts.js - import { Controller } from '@ember/controller'; - - export default Controller.extend({ - // ... - }); - - When the application is initialized, `ApplicationStore` will automatically be - instantiated, and the instance of `PostsController` will have its `store` - property set to that instance. - - Note that this code will only be run if the `ember-application` package is - loaded. If Ember Data is being used in an environment other than a - typical application (e.g., node.js where only `ember-runtime` is available), - this code will be ignored. + It ensures that the `store` service is automatically injected + as the `store` property on all routes and controllers. */ - export default { name: 'ember-data', initialize: setupContainer, diff --git a/packages/-ember-data/tests/helpers/custom-adapter.js b/packages/-ember-data/tests/helpers/custom-adapter.js deleted file mode 100644 index 7e174c1520b..00000000000 --- a/packages/-ember-data/tests/helpers/custom-adapter.js +++ /dev/null @@ -1,12 +0,0 @@ -import { run } from '@ember/runloop'; -import DS from 'ember-data'; - -export default function(env, adapterDefinition) { - let adapter = adapterDefinition; - if (!DS.Adapter.detect(adapterDefinition)) { - adapter = DS.Adapter.extend(adapterDefinition); - } - let store = env.store; - env.owner.register('adapter:-custom', adapter); - run(() => store.set('adapter', '-custom')); -} diff --git a/packages/-ember-data/tests/integration/relationships/belongs-to-test.js b/packages/-ember-data/tests/integration/relationships/belongs-to-test.js index 0cf5dffa416..a47a31c5619 100644 --- a/packages/-ember-data/tests/integration/relationships/belongs-to-test.js +++ b/packages/-ember-data/tests/integration/relationships/belongs-to-test.js @@ -1033,7 +1033,7 @@ module('integration/relationship/belongs_to Belongs-To Relationships', function( assert.expectAssertion(() => { message.get('user'); - }, /You looked up the 'user' relationship on a 'message' with id 1 but some of the associated records were not loaded. Either make sure they are all loaded together with the parent record, or specify that the relationship is async \(`DS.belongsTo\({ async: true }\)`\)/); + }, /You looked up the 'user' relationship on a 'message' with id 1 but some of the associated records were not loaded. Either make sure they are all loaded together with the parent record, or specify that the relationship is async \(`belongsTo\({ async: true }\)`\)/); }); test('Rollbacking attributes for a deleted record restores implicit relationship - async', function(assert) { diff --git a/packages/adapter/addon/-private/build-url-mixin.js b/packages/adapter/addon/-private/build-url-mixin.js index b3ff1d0ab4b..9cfbb92d5dd 100644 --- a/packages/adapter/addon/-private/build-url-mixin.js +++ b/packages/adapter/addon/-private/build-url-mixin.js @@ -8,9 +8,6 @@ import { pluralize } from 'ember-inflector'; */ /** - - WARNING: This interface is likely to change in order to accommodate [RFC: Ember Data url templates](https://github.com/emberjs/rfcs/pull/4) - ## Using BuildURLMixin To use URL building, include the mixin when extending an adapter, and call `buildURL` where needed. @@ -41,7 +38,7 @@ export default Mixin.create({ By default, it pluralizes the type's name (for example, 'post' becomes 'posts' and 'person' becomes 'people'). To override the - pluralization see [pathForType](#method_pathForType). + pluralization see [pathForType](BuildUrlMixin/methods/pathForType?anchor=pathForType). If an ID is specified, it adds the ID to the path generated for the type, separated by a `/`. @@ -52,7 +49,7 @@ export default Mixin.create({ @method buildURL @param {String} modelName @param {(String|Array|Object)} id single id or array of ids or query - @param {(DS.Snapshot|Array)} snapshot single snapshot or array of snapshots + @param {(Snapshot|SnapshotRecordArray)} snapshot single snapshot or array of snapshots @param {String} requestType @param {Object} query object of query parameters to send for query requests. @return {String} url @@ -138,7 +135,7 @@ export default Mixin.create({ @method urlForFindRecord @param {String} id @param {String} modelName - @param {DS.Snapshot} snapshot + @param {Snapshot} snapshot @return {String} url */ @@ -163,7 +160,7 @@ export default Mixin.create({ @method urlForFindAll @param {String} modelName - @param {DS.SnapshotRecordArray} snapshot + @param {SnapshotRecordArray} snapshot @return {String} url */ urlForFindAll(modelName, snapshot) { @@ -273,7 +270,7 @@ export default Mixin.create({ @method urlForFindHasMany @param {String} id @param {String} modelName - @param {DS.Snapshot} snapshot + @param {Snapshot} snapshot @return {String} url */ urlForFindHasMany(id, modelName, snapshot) { @@ -300,7 +297,7 @@ export default Mixin.create({ @method urlForFindBelongsTo @param {String} id @param {String} modelName - @param {DS.Snapshot} snapshot + @param {Snapshot} snapshot @return {String} url */ urlForFindBelongsTo(id, modelName, snapshot) { @@ -325,7 +322,7 @@ export default Mixin.create({ @method urlForCreateRecord @param {String} modelName - @param {DS.Snapshot} snapshot + @param {Snapshot} snapshot @return {String} url */ urlForCreateRecord(modelName, snapshot) { @@ -350,7 +347,7 @@ export default Mixin.create({ @method urlForUpdateRecord @param {String} id @param {String} modelName - @param {DS.Snapshot} snapshot + @param {Snapshot} snapshot @return {String} url */ urlForUpdateRecord(id, modelName, snapshot) { @@ -375,7 +372,7 @@ export default Mixin.create({ @method urlForDeleteRecord @param {String} id @param {String} modelName - @param {DS.Snapshot} snapshot + @param {Snapshot} snapshot @return {String} url */ urlForDeleteRecord(id, modelName, snapshot) { diff --git a/packages/adapter/addon/error.js b/packages/adapter/addon/error.js index fbac0a5dedb..114d6cefee3 100644 --- a/packages/adapter/addon/error.js +++ b/packages/adapter/addon/error.js @@ -21,7 +21,7 @@ import { assert } from '@ember/debug'; - `ServerError` To create a custom error to signal a specific error state in communicating - with an external API, extend the `DS.AdapterError`. For example, if the + with an external API, extend the `AdapterError`. For example, if the external API exclusively used HTTP `503 Service Unavailable` to indicate it was closed for maintenance: diff --git a/packages/adapter/addon/adapter.js b/packages/adapter/addon/index.js similarity index 93% rename from packages/adapter/addon/adapter.js rename to packages/adapter/addon/index.js index 256dcabaf59..c7f1824eb5f 100644 --- a/packages/adapter/addon/adapter.js +++ b/packages/adapter/addon/index.js @@ -1,5 +1,6 @@ /** @module @ember-data/adapter + @main @ember-data/adapter */ import EmberObject from '@ember/object'; @@ -58,7 +59,6 @@ import EmberObject from '@ember/object'; @class Adapter @extends EmberObject */ - export default EmberObject.extend({ /** If you would like your adapter to use a custom serializer you can @@ -110,10 +110,10 @@ export default EmberObject.extend({ ``` @method findRecord - @param {DS.Store} store - @param {DS.Model} type + @param {Store} store + @param {Model} type @param {String} id - @param {DS.Snapshot} snapshot + @param {Snapshot} snapshot @return {Promise} promise */ findRecord: null, @@ -142,10 +142,10 @@ export default EmberObject.extend({ ``` @method findAll - @param {DS.Store} store - @param {DS.Model} type + @param {Store} store + @param {Model} type @param {undefined} neverSet a value is never provided to this argument - @param {DS.SnapshotRecordArray} snapshotRecordArray + @param {SnapshotRecordArray} snapshotRecordArray @return {Promise} promise */ findAll: null, @@ -174,10 +174,10 @@ export default EmberObject.extend({ ``` @method query - @param {DS.Store} store - @param {DS.Model} type + @param {Store} store + @param {Model} type @param {Object} query - @param {DS.AdapterPopulatedRecordArray} recordArray + @param {AdapterPopulatedRecordArray} recordArray @return {Promise} promise */ query: null, @@ -213,8 +213,8 @@ export default EmberObject.extend({ ``` @method queryRecord - @param {DS.Store} store - @param {subclass of DS.Model} type + @param {Store} store + @param {subclass of Model} type @param {Object} query @return {Promise} promise */ @@ -246,8 +246,8 @@ export default EmberObject.extend({ ``` @method generateIdForRecord - @param {DS.Store} store - @param {DS.Model} type the Model class of the record + @param {Store} store + @param {Model} type the Model class of the record @param {Object} inputProperties a hash of properties to set on the newly created record. @return {(String|Number)} id @@ -273,7 +273,7 @@ export default EmberObject.extend({ ``` @method serialize - @param {DS.Snapshot} snapshot + @param {Snapshot} snapshot @param {Object} options @return {Object} serialized snapshot */ @@ -317,9 +317,9 @@ export default EmberObject.extend({ ``` @method createRecord - @param {DS.Store} store - @param {DS.Model} type the Model class of the record - @param {DS.Snapshot} snapshot + @param {Store} store + @param {Model} type the Model class of the record + @param {Snapshot} snapshot @return {Promise} promise */ createRecord: null, @@ -369,9 +369,9 @@ export default EmberObject.extend({ ``` @method updateRecord - @param {DS.Store} store - @param {DS.Model} type the Model class of the record - @param {DS.Snapshot} snapshot + @param {Store} store + @param {Model} type the Model class of the record + @param {Snapshot} snapshot @return {Promise} promise */ updateRecord: null, @@ -413,9 +413,9 @@ export default EmberObject.extend({ ``` @method deleteRecord - @param {DS.Store} store - @param {DS.Model} type the Model class of the record - @param {DS.Snapshot} snapshot + @param {Store} store + @param {Model} type the Model class of the record + @param {Snapshot} snapshot @return {Promise} promise */ deleteRecord: null, @@ -462,8 +462,8 @@ export default EmberObject.extend({ ``` @method findMany - @param {DS.Store} store - @param {DS.Model} type the Model class of the records + @param {Store} store + @param {Model} type the Model class of the records @param {Array} ids @param {Array} snapshots @return {Promise} promise @@ -480,7 +480,7 @@ export default EmberObject.extend({ The default implementation returns the records as a single group. @method groupRecordsForFindMany - @param {DS.Store} store + @param {Store} store @param {Array} snapshots @return {Array} an array of arrays of records, each of which is to be loaded separately by `findMany`. @@ -531,8 +531,8 @@ export default EmberObject.extend({ @since 1.13.0 @method shouldReloadRecord - @param {DS.Store} store - @param {DS.Snapshot} snapshot + @param {Store} store + @param {Snapshot} snapshot @return {Boolean} */ shouldReloadRecord(store, snapshot) { @@ -586,8 +586,8 @@ export default EmberObject.extend({ @since 1.13.0 @method shouldReloadAll - @param {DS.Store} store - @param {DS.SnapshotRecordArray} snapshotRecordArray + @param {Store} store + @param {SnapshotRecordArray} snapshotRecordArray @return {Boolean} */ shouldReloadAll(store, snapshotRecordArray) { @@ -622,8 +622,8 @@ export default EmberObject.extend({ @since 1.13.0 @method shouldBackgroundReloadRecord - @param {DS.Store} store - @param {DS.Snapshot} snapshot + @param {Store} store + @param {Snapshot} snapshot @return {Boolean} */ shouldBackgroundReloadRecord(store, snapshot) { @@ -658,11 +658,13 @@ export default EmberObject.extend({ @since 1.13.0 @method shouldBackgroundReloadAll - @param {DS.Store} store - @param {DS.SnapshotRecordArray} snapshotRecordArray + @param {Store} store + @param {SnapshotRecordArray} snapshotRecordArray @return {Boolean} */ shouldBackgroundReloadAll(store, snapshotRecordArray) { return true; }, }); + +export { BuildURLMixin } from './-private'; diff --git a/packages/adapter/addon/index.ts b/packages/adapter/addon/index.ts deleted file mode 100644 index 7e47e977bf4..00000000000 --- a/packages/adapter/addon/index.ts +++ /dev/null @@ -1,6 +0,0 @@ -/** - @module @ember-data/adapter -*/ - -export { BuildURLMixin } from './-private'; -export { default } from './adapter'; diff --git a/packages/adapter/addon/rest.js b/packages/adapter/addon/rest.js index f0f9c86f671..ab1a1a2efe5 100644 --- a/packages/adapter/addon/rest.js +++ b/packages/adapter/addon/rest.js @@ -265,7 +265,7 @@ const hasNajax = typeof najax !== 'undefined'; In some cases, your dynamic headers may require data from some object outside of Ember's observer system (for example `document.cookie`). You can use the - [volatile](/api/classes/Ember.ComputedProperty.html#method_volatile) + [volatile](/api/classes/Ember.ComputedProperty.html?anchor=volatile) function to set the property into a non-cached mode causing the headers to be recomputed with every request. @@ -456,7 +456,7 @@ const RESTAdapter = Adapter.extend(BuildURLMixin, { key. Arbitrary headers can be set as key/value pairs on the `RESTAdapter`'s `headers` object and Ember Data will send them along with each ajax request. For dynamic headers see [headers - customization](/api/data/classes/DS.RESTAdapter.html). + customization](/ember-data/release/classes/RESTAdapter). ```app/adapters/application.js import RESTAdapter from '@ember-data/adapter/rest'; @@ -487,10 +487,10 @@ const RESTAdapter = Adapter.extend(BuildURLMixin, { @since 1.13.0 @method findRecord - @param {DS.Store} store - @param {DS.Model} type + @param {Store} store + @param {Model} type @param {String} id - @param {DS.Snapshot} snapshot + @param {Snapshot} snapshot @return {Promise} promise */ findRecord(store, type, id, snapshot) { @@ -508,10 +508,10 @@ const RESTAdapter = Adapter.extend(BuildURLMixin, { promise for the resulting payload. @method findAll - @param {DS.Store} store - @param {DS.Model} type + @param {Store} store + @param {Model} type @param {undefined} neverSet a value is never provided to this argument - @param {DS.SnapshotRecordArray} snapshotRecordArray + @param {SnapshotRecordArray} snapshotRecordArray @return {Promise} promise */ findAll(store, type, sinceToken, snapshotRecordArray) { @@ -537,8 +537,8 @@ const RESTAdapter = Adapter.extend(BuildURLMixin, { to the server as parameters. @method query - @param {DS.Store} store - @param {DS.Model} type + @param {Store} store + @param {Model} type @param {Object} query @return {Promise} promise */ @@ -565,8 +565,8 @@ const RESTAdapter = Adapter.extend(BuildURLMixin, { @since 1.13.0 @method queryRecord - @param {DS.Store} store - @param {DS.Model} type + @param {Store} store + @param {Model} type @param {Object} query @return {Promise} promise */ @@ -607,8 +607,8 @@ const RESTAdapter = Adapter.extend(BuildURLMixin, { promise for the resulting payload. @method findMany - @param {DS.Store} store - @param {DS.Model} type + @param {Store} store + @param {Model} type @param {Array} ids @param {Array} snapshots @return {Promise} promise @@ -648,8 +648,8 @@ const RESTAdapter = Adapter.extend(BuildURLMixin, { * Links with no beginning `/` will have a parentURL prepended to it, via the current adapter's `buildURL`. @method findHasMany - @param {DS.Store} store - @param {DS.Snapshot} snapshot + @param {Store} store + @param {Snapshot} snapshot @param {String} url @param {Object} relationship meta object describing the relationship @return {Promise} promise @@ -693,8 +693,8 @@ const RESTAdapter = Adapter.extend(BuildURLMixin, { * Links with no beginning `/` will have a parentURL prepended to it, via the current adapter's `buildURL`. @method findBelongsTo - @param {DS.Store} store - @param {DS.Snapshot} snapshot + @param {Store} store + @param {Snapshot} snapshot @param {String} url @param {Object} relationship meta object describing the relationship @return {Promise} promise @@ -718,9 +718,9 @@ const RESTAdapter = Adapter.extend(BuildURLMixin, { of a record. @method createRecord - @param {DS.Store} store - @param {DS.Model} type - @param {DS.Snapshot} snapshot + @param {Store} store + @param {Model} type + @param {Snapshot} snapshot @return {Promise} promise */ createRecord(store, type, snapshot) { @@ -742,9 +742,9 @@ const RESTAdapter = Adapter.extend(BuildURLMixin, { of a record. @method updateRecord - @param {DS.Store} store - @param {DS.Model} type - @param {DS.Snapshot} snapshot + @param {Store} store + @param {Model} type + @param {Snapshot} snapshot @return {Promise} promise */ updateRecord(store, type, snapshot) { @@ -762,9 +762,9 @@ const RESTAdapter = Adapter.extend(BuildURLMixin, { The `deleteRecord` method makes an Ajax (HTTP DELETE) request to a URL computed by `buildURL`. @method deleteRecord - @param {DS.Store} store - @param {DS.Model} type - @param {DS.Snapshot} snapshot + @param {Store} store + @param {Model} type + @param {Snapshot} snapshot @return {Promise} promise */ deleteRecord(store, type, snapshot) { @@ -814,7 +814,7 @@ const RESTAdapter = Adapter.extend(BuildURLMixin, { and `/posts/2/comments/3` @method groupRecordsForFindMany - @param {DS.Store} store + @param {Store} store @param {Array} snapshots @return {Array} an array of arrays of records, each of which is to be loaded separately by `findMany`. @@ -892,7 +892,7 @@ const RESTAdapter = Adapter.extend(BuildURLMixin, { @param {Object} headers @param {Object} payload @param {Object} requestData - the original request information - @return {Object | DS.AdapterError} response + @return {Object | AdapterError} response */ handleResponse(status, headers, payload, requestData) { if (this.isSuccess(status, headers, payload)) { @@ -1335,7 +1335,7 @@ function headersToObject(headers) { /** * Helper function that translates the options passed to `jQuery.ajax` into a format that `fetch` expects. * @param {Object} _options - * @param {DS.Adapter} adapter + * @param {Adapter} adapter * @returns {Object} */ export function fetchOptions(options, adapter) { diff --git a/packages/model/addon/-private/attr.js b/packages/model/addon/-private/attr.js index 2452009384b..e172ff332d5 100644 --- a/packages/model/addon/-private/attr.js +++ b/packages/model/addon/-private/attr.js @@ -26,12 +26,12 @@ function hasValue(internalModel, key) { } /** - `attr` defines an attribute on a [Model](/api/data/classes/DS.Model.html). + `attr` defines an attribute on a [Model](/ember-data/release/classes/Model). By default, attributes are passed through as-is, however you can specify an optional type to have the value automatically transformed. Ember Data ships with four basic transform types: `string`, `number`, `boolean` and `date`. You can define your own transforms by subclassing - [Transform](/api/data/classes/DS.Transform.html). + [Transform](/ember-data/release/classes/Transform). Note that you cannot use `attr` to define an attribute of `id`. diff --git a/packages/model/addon/-private/belongs-to.js b/packages/model/addon/-private/belongs-to.js index 1da9d0dcaee..014f5063afc 100644 --- a/packages/model/addon/-private/belongs-to.js +++ b/packages/model/addon/-private/belongs-to.js @@ -9,7 +9,7 @@ import { DEBUG } from '@glimmer/env'; /** `belongsTo` is used to define One-To-One and One-To-Many - relationships on a [Model](/api/data/classes/DS.Model.html). + relationships on a [Model](/ember-data/release/classes/Model). `belongsTo` takes an optional hash as a second parameter, currently @@ -148,7 +148,7 @@ export default function belongsTo(modelName, options) { } if (opts.hasOwnProperty('serialize')) { warn( - `You provided a serialize option on the "${key}" property in the "${this._internalModel.modelName}" class, this belongs in the serializer. See Serializer and it's implementations https://emberjs.com/api/data/classes/DS.Serializer.html`, + `You provided a serialize option on the "${key}" property in the "${this._internalModel.modelName}" class, this belongs in the serializer. See Serializer and it's implementations https://api.emberjs.com/ember-data/release/classes/Serializer`, false, { id: 'ds.model.serialize-option-in-belongs-to', @@ -158,7 +158,7 @@ export default function belongsTo(modelName, options) { if (opts.hasOwnProperty('embedded')) { warn( - `You provided an embedded option on the "${key}" property in the "${this._internalModel.modelName}" class, this belongs in the serializer. See EmbeddedRecordsMixin https://emberjs.com/api/data/classes/DS.EmbeddedRecordsMixin.html`, + `You provided an embedded option on the "${key}" property in the "${this._internalModel.modelName}" class, this belongs in the serializer. See EmbeddedRecordsMixin https://api.emberjs.com/ember-data/release/classes/EmbeddedRecordsMixin`, false, { id: 'ds.model.embedded-option-in-belongs-to', diff --git a/packages/model/addon/-private/has-many.js b/packages/model/addon/-private/has-many.js index 99e03a18f7f..9892506b01a 100644 --- a/packages/model/addon/-private/has-many.js +++ b/packages/model/addon/-private/has-many.js @@ -8,7 +8,7 @@ import { DEBUG } from '@glimmer/env'; /** `hasMany` is used to define One-To-Many and Many-To-Many - relationships on a [Model](/api/data/classes/DS.Model.html). + relationships on a [Model](/ember-data/release/classes/Model). `hasMany` takes an optional hash as a second parameter, currently supported options are: @@ -122,7 +122,7 @@ import { DEBUG } from '@glimmer/env'; ``` In contrast to async relationship, accessing a sync relationship - will always return a [ManyArray](/api/data/classes/DS.ManyArray.html) instance + will always return a [ManyArray](/ember-data/release/classes/ManyArray) instance containing the existing local resources. But it will error on access when any of the known related resources have not been loaded. diff --git a/packages/model/addon/-private/index.ts b/packages/model/addon/-private/index.ts index c7688a031b5..e36922275ca 100644 --- a/packages/model/addon/-private/index.ts +++ b/packages/model/addon/-private/index.ts @@ -1,7 +1,3 @@ -/** - @module @ember-data/model -*/ - export { default as attr } from './attr'; export { default as belongsTo } from './belongs-to'; export { default as hasMany } from './has-many'; diff --git a/packages/model/addon/index.ts b/packages/model/addon/index.ts index 834d7d51e0d..5836e5c191c 100644 --- a/packages/model/addon/index.ts +++ b/packages/model/addon/index.ts @@ -1,6 +1,43 @@ /** + In EmberData a `Model` is a class defining the attributes and relationships + of a specific resource `type` (model name). In this sense it represents a static "schema". + + Data for individual resources fetched from your API is presented + to the UI via instances of the `Model`s you define. + + An instantiated `Model` is refered to as a `record`. + + When we refer to the `ModelClass` we are referring to the class definition + and the static schema methods present on it. + + When we refer to a `record` we refer to a specific class instance presenting + the resource data for a given `type` and `id`. + + ### Defining a Model + + ```app/models/person.js + import Model, { attr, belongsTo, hasMany } from '@ember-data/model'; + + export default Model.extend({ + name: attr(), + + dog: belongsTo('pet', { inverse: 'owners', async: false }), + + friends: hasMany('person', { inverse: 'friends', async: true }), + }); + ``` + + ### modelName convention + + By convention, the name of a given model (its `type`) matches the name + of the file in the `app/models` folder and should be lowercase, singular + and dasherized. + @module @ember-data/model -*/ + @main @ember-data/model + @class Model + @public + */ export { attr, belongsTo, hasMany } from './-private'; export { Model as default } from '@ember-data/store/-private'; diff --git a/packages/model/blueprints/model/HELP.md b/packages/model/blueprints/model/HELP.md index caba05ddbac..ba76d7dcbb9 100644 --- a/packages/model/blueprints/model/HELP.md +++ b/packages/model/blueprints/model/HELP.md @@ -1,26 +1,26 @@ You may generate models with as many attrs as you would like to pass. The following attribute types are supported: - - :array - :boolean - :date - :object - :number - :string - :your-custom-transform - :belongs-to: - :has-many: + +:array +:boolean +:date +:object +:number +:string +:your-custom-transform +:belongs-to: +:has-many: For instance: \`ember generate model taco filling:belongs-to:protein toppings:has-many:toppings name:string price:number misc\` would result in the following model: ```js -import DS from 'ember-data'; +import Model, { belongsTo, hasMany, attr } from '@ember-data/model'; -export default DS.Model.extend({ - filling: DS.belongsTo('protein'), - toppings: DS.hasMany('topping'), - name: DS.attr('string'), - price: DS.attr('number'), - misc: DS.attr() +export default Model.extend({ + filling: belongsTo('protein'), + toppings: hasMany('topping'), + name: attr('string'), + price: attr('number'), + misc: attr(), }); ``` diff --git a/packages/serializer/addon/-private/embedded-records-mixin.js b/packages/serializer/addon/-private/embedded-records-mixin.js index 5767675d741..985869a9dc0 100644 --- a/packages/serializer/addon/-private/embedded-records-mixin.js +++ b/packages/serializer/addon/-private/embedded-records-mixin.js @@ -94,9 +94,9 @@ import { warn } from '@ember/debug'; to modify it to fit your specific needs.** For example, review the docs for each method of this mixin: - * [normalize](/api/data/classes/DS.EmbeddedRecordsMixin.html#method_normalize) - * [serializeBelongsTo](/api/data/classes/DS.EmbeddedRecordsMixin.html#method_serializeBelongsTo) - * [serializeHasMany](/api/data/classes/DS.EmbeddedRecordsMixin.html#method_serializeHasMany) + * [normalize](/ember-data/release/classes/EmbeddedRecordsMixin/methods/normalize?anchor=normalize) + * [serializeBelongsTo](/ember-data/release/classes/EmbeddedRecordsMixin/methods/serializeBelongsTo?anchor=serializeBelongsTo) + * [serializeHasMany](/ember-data/release/classes/EmbeddedRecordsMixin/methods/serializeHasMany?anchor=serializeHasMany) @class EmbeddedRecordsMixin */ @@ -123,7 +123,7 @@ export default Mixin.create({ } ``` @method normalize - @param {DS.Model} typeClass + @param {Model} typeClass @param {Object} hash to be normalized @param {String} prop the hash has been referenced by @return {Object} the normalized hash @@ -193,7 +193,7 @@ export default Mixin.create({ ``` @method serializeBelongsTo - @param {DS.Snapshot} snapshot + @param {Snapshot} snapshot @param {Object} json @param {Object} relationship */ @@ -336,13 +336,13 @@ export default Mixin.create({ For example having a user that has many pets: ```js - User = DS.Model.extend({ - name: DS.attr('string'), - pets: DS.hasMany('pet', { polymorphic: true }) + User = Model.extend({ + name: attr('string'), + pets: hasMany('pet', { polymorphic: true }) }); - Pet = DS.Model.extend({ - name: DS.attr('string'), + Pet = Model.extend({ + name: attr('string'), }); Cat = Pet.extend({ @@ -378,7 +378,7 @@ export default Mixin.create({ ``` @method serializeHasMany - @param {DS.Snapshot} snapshot + @param {Snapshot} snapshot @param {Object} json @param {Object} relationship */ @@ -470,8 +470,8 @@ export default Mixin.create({ the parent record. @method removeEmbeddedForeignKey - @param {DS.Snapshot} snapshot - @param {DS.Snapshot} embeddedSnapshot + @param {Snapshot} snapshot + @param {Snapshot} embeddedSnapshot @param {Object} relationship @param {Object} json */ diff --git a/packages/serializer/addon/-private/transforms/boolean.js b/packages/serializer/addon/-private/transforms/boolean.js index ddf83b62c56..0c0249e10ff 100644 --- a/packages/serializer/addon/-private/transforms/boolean.js +++ b/packages/serializer/addon/-private/transforms/boolean.js @@ -9,7 +9,7 @@ import Transform from './transform'; The `BooleanTransform` class is used to serialize and deserialize boolean attributes on Ember Data record objects. This transform is used when `boolean` is passed as the type parameter to the - [DS.attr](../../data#method_attr) function. + [attr](/ember-data/release/functions/@ember-data%2Fmodel/attr) function. Usage diff --git a/packages/serializer/addon/-private/transforms/date.js b/packages/serializer/addon/-private/transforms/date.js index 3d20995bf77..206b6009542 100644 --- a/packages/serializer/addon/-private/transforms/date.js +++ b/packages/serializer/addon/-private/transforms/date.js @@ -8,7 +8,7 @@ import Transform from './transform'; The `DateTransform` class is used to serialize and deserialize date attributes on Ember Data record objects. This transform is used when `date` is passed as the type parameter to the - [DS.attr](../../data#method_attr) function. It uses the [`ISO 8601`](https://en.wikipedia.org/wiki/ISO_8601) + [attr](/ember-data/release/functions/@ember-data%2Fmodel/attr) function. It uses the [`ISO 8601`](https://en.wikipedia.org/wiki/ISO_8601) standard. ```app/models/score.js diff --git a/packages/serializer/addon/-private/transforms/number.js b/packages/serializer/addon/-private/transforms/number.js index 3cd12162945..6fe31af8240 100644 --- a/packages/serializer/addon/-private/transforms/number.js +++ b/packages/serializer/addon/-private/transforms/number.js @@ -12,7 +12,7 @@ function isNumber(value) { The `NumberTransform` class is used to serialize and deserialize numeric attributes on Ember Data record objects. This transform is used when `number` is passed as the type parameter to the - [DS.attr](../../data#method_attr) function. + [attr](/ember-data/release/functions/@ember-data%2Fmodel/attr) function. Usage diff --git a/packages/serializer/addon/-private/transforms/string.js b/packages/serializer/addon/-private/transforms/string.js index 29f0b638f23..42a89882663 100644 --- a/packages/serializer/addon/-private/transforms/string.js +++ b/packages/serializer/addon/-private/transforms/string.js @@ -9,7 +9,7 @@ import Transform from './transform'; The `StringTransform` class is used to serialize and deserialize string attributes on Ember Data record objects. This transform is used when `string` is passed as the type parameter to the - [DS.attr](./DS/methods/attr?anchor=attr) function. + [attr](/ember-data/release/functions/@ember-data%2Fmodel/attr) function. Usage diff --git a/packages/serializer/addon/serializer.js b/packages/serializer/addon/index.js similarity index 94% rename from packages/serializer/addon/serializer.js rename to packages/serializer/addon/index.js index 694a3f6b16f..f2ef4d0e95c 100644 --- a/packages/serializer/addon/serializer.js +++ b/packages/serializer/addon/index.js @@ -1,5 +1,6 @@ /** @module @ember-data/serializer + @main @ember-data/serializer */ import EmberObject from '@ember/object'; @@ -17,7 +18,7 @@ import EmberObject from '@ember/object'; * `normalize()` For an example implementation, see - [DS.JSONSerializer](DS.JSONSerializer), the included JSON serializer. + [JSONSerializer](JSONSerializer), the included JSON serializer. @class Serializer @extends EmberObject @@ -42,7 +43,7 @@ export default EmberObject.extend({ ``` @property store - @type {DS.Store} + @type {Store} @public */ @@ -73,8 +74,8 @@ export default EmberObject.extend({ @since 1.13.0 @method normalizeResponse - @param {DS.Store} store - @param {DS.Model} primaryModelClass + @param {Store} store + @param {Model} primaryModelClass @param {Object} payload @param {String|Number} id @param {String} requestType @@ -118,7 +119,7 @@ export default EmberObject.extend({ ``` @method serialize - @param {DS.Snapshot} snapshot + @param {Snapshot} snapshot @param {Object} [options] @return {Object} */ @@ -146,7 +147,7 @@ export default EmberObject.extend({ ``` @method normalize - @param {DS.Model} typeClass + @param {Model} typeClass @param {Object} hash @return {Object} */ diff --git a/packages/serializer/addon/index.ts b/packages/serializer/addon/index.ts deleted file mode 100644 index 68b6f7c4e79..00000000000 --- a/packages/serializer/addon/index.ts +++ /dev/null @@ -1,5 +0,0 @@ -/** - @module @ember-data/serializer -*/ - -export { default } from './serializer'; diff --git a/packages/serializer/addon/json-api.js b/packages/serializer/addon/json-api.js index ab663c1d4cc..a0ba798c6b3 100644 --- a/packages/serializer/addon/json-api.js +++ b/packages/serializer/addon/json-api.js @@ -208,7 +208,7 @@ const JSONAPISerializer = JSONSerializer.extend({ /** @method pushPayload - @param {DS.Store} store + @param {Store} store @param {Object} payload */ pushPayload(store, payload) { @@ -218,8 +218,8 @@ const JSONAPISerializer = JSONSerializer.extend({ /** @method _normalizeResponse - @param {DS.Store} store - @param {DS.Model} primaryModelClass + @param {Store} store + @param {Model} primaryModelClass @param {Object} payload @param {String|Number} id @param {String} requestType @@ -336,7 +336,7 @@ const JSONAPISerializer = JSONSerializer.extend({ /** @method _extractType - @param {DS.Model} modelClass + @param {Model} modelClass @param {Object} resourceHash @return {String} @private @@ -556,7 +556,7 @@ if (DEBUG) { willMergeMixin(props) { let constructor = this.constructor; warn( - `You've defined 'extractMeta' in ${constructor.toString()} which is not used for serializers extending JSONAPISerializer. Read more at https://emberjs.com/api/data/classes/DS.JSONAPISerializer on how to customize meta when using JSON API.`, + `You've defined 'extractMeta' in ${constructor.toString()} which is not used for serializers extending JSONAPISerializer. Read more at https://api.emberjs.com/ember-data/release/classes/JSONAPISerializer on how to customize meta when using JSON API.`, isNone(props.extractMeta) || props.extractMeta === JSONSerializer.prototype.extractMeta, { id: 'ds.serializer.json-api.extractMeta', diff --git a/packages/serializer/addon/json.js b/packages/serializer/addon/json.js index 4d05f7e3a54..39e5b3232f5 100644 --- a/packages/serializer/addon/json.js +++ b/packages/serializer/addon/json.js @@ -184,7 +184,7 @@ const JSONSerializer = Serializer.extend({ @method applyTransforms @private - @param {DS.Model} typeClass + @param {Model} typeClass @param {Object} data The data to transform @return {Object} data The transformed data object */ @@ -232,8 +232,8 @@ const JSONSerializer = Serializer.extend({ @since 1.13.0 @method normalizeResponse - @param {DS.Store} store - @param {DS.Model} primaryModelClass + @param {Store} store + @param {Model} primaryModelClass @param {Object} payload @param {String|Number} id @param {String} requestType @@ -267,8 +267,8 @@ const JSONSerializer = Serializer.extend({ /** @since 1.13.0 @method normalizeFindRecordResponse - @param {DS.Store} store - @param {DS.Model} primaryModelClass + @param {Store} store + @param {Model} primaryModelClass @param {Object} payload @param {String|Number} id @param {String} requestType @@ -281,8 +281,8 @@ const JSONSerializer = Serializer.extend({ /** @since 1.13.0 @method normalizeQueryRecordResponse - @param {DS.Store} store - @param {DS.Model} primaryModelClass + @param {Store} store + @param {Model} primaryModelClass @param {Object} payload @param {String|Number} id @param {String} requestType @@ -295,8 +295,8 @@ const JSONSerializer = Serializer.extend({ /** @since 1.13.0 @method normalizeFindAllResponse - @param {DS.Store} store - @param {DS.Model} primaryModelClass + @param {Store} store + @param {Model} primaryModelClass @param {Object} payload @param {String|Number} id @param {String} requestType @@ -309,8 +309,8 @@ const JSONSerializer = Serializer.extend({ /** @since 1.13.0 @method normalizeFindBelongsToResponse - @param {DS.Store} store - @param {DS.Model} primaryModelClass + @param {Store} store + @param {Model} primaryModelClass @param {Object} payload @param {String|Number} id @param {String} requestType @@ -323,8 +323,8 @@ const JSONSerializer = Serializer.extend({ /** @since 1.13.0 @method normalizeFindHasManyResponse - @param {DS.Store} store - @param {DS.Model} primaryModelClass + @param {Store} store + @param {Model} primaryModelClass @param {Object} payload @param {String|Number} id @param {String} requestType @@ -337,8 +337,8 @@ const JSONSerializer = Serializer.extend({ /** @since 1.13.0 @method normalizeFindManyResponse - @param {DS.Store} store - @param {DS.Model} primaryModelClass + @param {Store} store + @param {Model} primaryModelClass @param {Object} payload @param {String|Number} id @param {String} requestType @@ -351,8 +351,8 @@ const JSONSerializer = Serializer.extend({ /** @since 1.13.0 @method normalizeQueryResponse - @param {DS.Store} store - @param {DS.Model} primaryModelClass + @param {Store} store + @param {Model} primaryModelClass @param {Object} payload @param {String|Number} id @param {String} requestType @@ -365,8 +365,8 @@ const JSONSerializer = Serializer.extend({ /** @since 1.13.0 @method normalizeCreateRecordResponse - @param {DS.Store} store - @param {DS.Model} primaryModelClass + @param {Store} store + @param {Model} primaryModelClass @param {Object} payload @param {String|Number} id @param {String} requestType @@ -379,8 +379,8 @@ const JSONSerializer = Serializer.extend({ /** @since 1.13.0 @method normalizeDeleteRecordResponse - @param {DS.Store} store - @param {DS.Model} primaryModelClass + @param {Store} store + @param {Model} primaryModelClass @param {Object} payload @param {String|Number} id @param {String} requestType @@ -393,8 +393,8 @@ const JSONSerializer = Serializer.extend({ /** @since 1.13.0 @method normalizeUpdateRecordResponse - @param {DS.Store} store - @param {DS.Model} primaryModelClass + @param {Store} store + @param {Model} primaryModelClass @param {Object} payload @param {String|Number} id @param {String} requestType @@ -407,8 +407,8 @@ const JSONSerializer = Serializer.extend({ /** @since 1.13.0 @method normalizeSaveResponse - @param {DS.Store} store - @param {DS.Model} primaryModelClass + @param {Store} store + @param {Model} primaryModelClass @param {Object} payload @param {String|Number} id @param {String} requestType @@ -421,8 +421,8 @@ const JSONSerializer = Serializer.extend({ /** @since 1.13.0 @method normalizeSingleResponse - @param {DS.Store} store - @param {DS.Model} primaryModelClass + @param {Store} store + @param {Model} primaryModelClass @param {Object} payload @param {String|Number} id @param {String} requestType @@ -435,8 +435,8 @@ const JSONSerializer = Serializer.extend({ /** @since 1.13.0 @method normalizeArrayResponse - @param {DS.Store} store - @param {DS.Model} primaryModelClass + @param {Store} store + @param {Model} primaryModelClass @param {Object} payload @param {String|Number} id @param {String} requestType @@ -448,8 +448,8 @@ const JSONSerializer = Serializer.extend({ /** @method _normalizeResponse - @param {DS.Store} store - @param {DS.Model} primaryModelClass + @param {Store} store + @param {Model} primaryModelClass @param {Object} payload @param {String|Number} id @param {String} requestType @@ -532,7 +532,7 @@ const JSONSerializer = Serializer.extend({ ``` @method normalize - @param {DS.Model} typeClass + @param {Model} typeClass @param {Object} hash @return {Object} */ @@ -867,7 +867,7 @@ const JSONSerializer = Serializer.extend({ This could be configured per relationship by Serializer's `attrs` object. @method shouldSerializeHasMany - @param {DS.Snapshot} snapshot + @param {Snapshot} snapshot @param {String} key @param {String} relationshipType @return {boolean} true if the hasMany relationship should be serialized @@ -1029,7 +1029,7 @@ const JSONSerializer = Serializer.extend({ ``` @method serialize - @param {DS.Snapshot} snapshot + @param {Snapshot} snapshot @param {Object} options @return {Object} json */ @@ -1082,8 +1082,8 @@ const JSONSerializer = Serializer.extend({ @method serializeIntoHash @param {Object} hash - @param {DS.Model} typeClass - @param {DS.Snapshot} snapshot + @param {Model} typeClass + @param {Snapshot} snapshot @param {Object} options */ serializeIntoHash(hash, typeClass, snapshot, options) { @@ -1110,7 +1110,7 @@ const JSONSerializer = Serializer.extend({ ``` @method serializeAttribute - @param {DS.Snapshot} snapshot + @param {Snapshot} snapshot @param {Object} json @param {String} key @param {Object} attribute @@ -1159,7 +1159,7 @@ const JSONSerializer = Serializer.extend({ ``` @method serializeBelongsTo - @param {DS.Snapshot} snapshot + @param {Snapshot} snapshot @param {Object} json @param {Object} relationship */ @@ -1212,7 +1212,7 @@ const JSONSerializer = Serializer.extend({ ``` @method serializeHasMany - @param {DS.Snapshot} snapshot + @param {Snapshot} snapshot @param {Object} json @param {Object} relationship */ @@ -1264,7 +1264,7 @@ const JSONSerializer = Serializer.extend({ ``` @method serializePolymorphicType - @param {DS.Snapshot} snapshot + @param {Snapshot} snapshot @param {Object} json @param {Object} relationship */ @@ -1292,8 +1292,8 @@ const JSONSerializer = Serializer.extend({ ``` @method extractMeta - @param {DS.Store} store - @param {DS.Model} modelClass + @param {Store} store + @param {Model} modelClass @param {Object} payload */ extractMeta(store, modelClass, payload) { @@ -1383,8 +1383,8 @@ const JSONSerializer = Serializer.extend({ ``` @method extractErrors - @param {DS.Store} store - @param {DS.Model} typeClass + @param {Store} store + @param {Model} typeClass @param {Object} payload @param {(String|Number)} id @return {Object} json The deserialized errors @@ -1489,7 +1489,7 @@ const JSONSerializer = Serializer.extend({ @private @param {String} attributeType @param {Boolean} skipAssertion - @return {DS.Transform} transform + @return {Transform} transform */ transformFor(attributeType, skipAssertion) { let transform = getOwner(this).lookup('transform:' + attributeType); diff --git a/packages/serializer/addon/rest.js b/packages/serializer/addon/rest.js index f5d120ddec2..dd075aa584b 100644 --- a/packages/serializer/addon/rest.js +++ b/packages/serializer/addon/rest.js @@ -150,7 +150,7 @@ const RESTSerializer = JSONSerializer.extend({ normalization as `normalizeResponse`. @method normalize - @param {DS.Model} modelClass + @param {Model} modelClass @param {Object} resourceHash @param {String} prop @return {Object} @@ -161,7 +161,7 @@ const RESTSerializer = JSONSerializer.extend({ with primary data and, if any, included data as `{ data, included }`. @method _normalizeArray - @param {DS.Store} store + @param {Store} store @param {String} modelName @param {Object} arrayHash @param {String} prop @@ -209,8 +209,8 @@ const RESTSerializer = JSONSerializer.extend({ /* @method _normalizeResponse - @param {DS.Store} store - @param {DS.Model} primaryModelClass + @param {Store} store + @param {Model} primaryModelClass @param {Object} payload @param {String|Number} id @param {String} requestType @@ -383,7 +383,7 @@ const RESTSerializer = JSONSerializer.extend({ that fetches and saves are structured. @method pushPayload - @param {DS.Store} store + @param {Store} store @param {Object} payload */ pushPayload(store, payload) { @@ -627,7 +627,7 @@ const RESTSerializer = JSONSerializer.extend({ ``` @method serialize - @param {DS.Snapshot} snapshot + @param {Snapshot} snapshot @param {Object} options @return {Object} json */ @@ -657,8 +657,8 @@ const RESTSerializer = JSONSerializer.extend({ @method serializeIntoHash @param {Object} hash - @param {DS.Model} typeClass - @param {DS.Snapshot} snapshot + @param {Model} typeClass + @param {Snapshot} snapshot @param {Object} options */ serializeIntoHash(hash, typeClass, snapshot, options) { @@ -722,7 +722,7 @@ const RESTSerializer = JSONSerializer.extend({ the attribute and value from the model's camelcased model name. @method serializePolymorphicType - @param {DS.Snapshot} snapshot + @param {Snapshot} snapshot @param {Object} json @param {Object} relationship */ diff --git a/packages/store/addon/-private/system/many-array.js b/packages/store/addon/-private/system/many-array.js index cc96e8a6bda..7b425275ee3 100644 --- a/packages/store/addon/-private/system/many-array.js +++ b/packages/store/addon/-private/system/many-array.js @@ -271,7 +271,7 @@ export default EmberObject.extend(MutableArray, DeprecatedEvent, { ``` @method save - @return {DS.PromiseArray} promise + @return {PromiseArray} promise */ save() { let manyArray = this; @@ -291,7 +291,7 @@ export default EmberObject.extend(MutableArray, DeprecatedEvent, { @method createRecord @private @param {Object} hash - @return {DS.Model} record + @return {Model} record */ createRecord(hash) { const store = get(this, 'store'); diff --git a/packages/store/addon/-private/system/model/internal-model.ts b/packages/store/addon/-private/system/model/internal-model.ts index c7e80121fd8..6de21fdf337 100644 --- a/packages/store/addon/-private/system/model/internal-model.ts +++ b/packages/store/addon/-private/system/model/internal-model.ts @@ -658,7 +658,7 @@ export default class InternalModel { parentInternalModel.modelName + "' with id " + parentInternalModel.id + - ' but some of the associated records were not loaded. Either make sure they are all loaded together with the parent record, or specify that the relationship is async (`DS.belongsTo({ async: true })`)', + ' but some of the associated records were not loaded. Either make sure they are all loaded together with the parent record, or specify that the relationship is async (`belongsTo({ async: true })`)', toReturn === null || !toReturn.get('isEmpty') ); return toReturn; @@ -745,7 +745,7 @@ export default class InternalModel { return this._updatePromiseProxyFor('hasMany', key, { promise, content: manyArray }); } else { assert( - `You looked up the '${key}' relationship on a '${this.type.modelName}' with id ${this.id} but some of the associated records were not loaded. Either make sure they are all loaded together with the parent record, or specify that the relationship is async ('DS.hasMany({ async: true })')`, + `You looked up the '${key}' relationship on a '${this.type.modelName}' with id ${this.id} but some of the associated records were not loaded. Either make sure they are all loaded together with the parent record, or specify that the relationship is async ('hasMany({ async: true })')`, !manyArray.anyUnloaded() ); diff --git a/packages/store/addon/-private/system/model/model.js b/packages/store/addon/-private/system/model/model.js index fbe1493c83c..bc640e79343 100644 --- a/packages/store/addon/-private/system/model/model.js +++ b/packages/store/addon/-private/system/model/model.js @@ -22,10 +22,6 @@ import coerceId from '../coerce-id'; const { changeProperties } = Ember; -/** - @module @ember-data/model -*/ - function findPossibleInverses(type, inverseType, name, relationshipsSoFar) { let possibleRelationships = relationshipsSoFar || []; @@ -98,12 +94,8 @@ if (RECORD_DATA_STATE) { } /** - - The model class that all Ember Data records descend from. - This is the public API of Ember Data models. If you are using Ember Data - in your application, this is the class you should use. - @class Model + @module @ember-data/model @extends EmberObject @uses EmberData.DeprecatedEvented */ @@ -529,7 +521,7 @@ const Model = EmberObject.extend(DeprecatedEvented, { }, /** - Use [JSONSerializer](DS.JSONSerializer.html) to + Use [JSONSerializer](JSONSerializer.html) to get the JSON representation of a record. `toJSON` takes an optional hash as a parameter, currently @@ -1314,7 +1306,7 @@ if (DEBUG) { if (idDesc.get !== ID_DESCRIPTOR.get) { throw new EmberError( - `You may not set 'id' as an attribute on your model. Please remove any lines that look like: \`id: DS.attr('')\` from ${this.constructor.toString()}` + `You may not set 'id' as an attribute on your model. Please remove any lines that look like: \`id: attr('')\` from ${this.constructor.toString()}` ); } }, diff --git a/packages/store/addon/-private/system/model/states.js b/packages/store/addon/-private/system/model/states.js index fc3ebe213f1..6385c15dc34 100644 --- a/packages/store/addon/-private/system/model/states.js +++ b/packages/store/addon/-private/system/model/states.js @@ -159,14 +159,14 @@ import { assert } from '@ember/debug'; `Model` class. - * [isEmpty](DS.Model.html#property_isEmpty) - * [isLoading](DS.Model.html#property_isLoading) - * [isLoaded](DS.Model.html#property_isLoaded) - * [hasDirtyAttributes](DS.Model.html#property_hasDirtyAttributes) - * [isSaving](DS.Model.html#property_isSaving) - * [isDeleted](DS.Model.html#property_isDeleted) - * [isNew](DS.Model.html#property_isNew) - * [isValid](DS.Model.html#property_isValid) + * [isEmpty](Model/properties/isEmpty?anchor=isEmpty) + * [isLoading](Model/properties/isLoading?anchor=isLoading) + * [isLoaded](Model/properties/isLoaded?anchor=isLoaded) + * [hasDirtyAttributes](Model/properties/hasDirtyAttributes?anchor=hasDirtyAttributes) + * [isSaving](Model/properties/isSaving?anchor=isSaving) + * [isDeleted](Model/properties/isDeleted?anchor=isDeleted) + * [isNew](Model/properties/isNew?anchor=isNew) + * [isValid](Model/properties/isValid?anchor=isValid) @class RootState */ diff --git a/packages/store/addon/-private/system/record-arrays/adapter-populated-record-array.js b/packages/store/addon/-private/system/record-arrays/adapter-populated-record-array.js index fb0cea70d89..f78b9558da7 100644 --- a/packages/store/addon/-private/system/record-arrays/adapter-populated-record-array.js +++ b/packages/store/addon/-private/system/record-arrays/adapter-populated-record-array.js @@ -18,7 +18,7 @@ import { DEBUG } from '@glimmer/env'; --- If you want to update the array and get the latest records from the - adapter, you can invoke [`update()`](#method_update): + adapter, you can invoke [`update()`](AdapterPopulatedRecordArray/methods/update?anchor=update): Example diff --git a/packages/store/addon/-private/system/store.ts b/packages/store/addon/-private/system/store.ts index 4a30044ea45..826c75c801c 100644 --- a/packages/store/addon/-private/system/store.ts +++ b/packages/store/addon/-private/system/store.ts @@ -68,12 +68,15 @@ let globalClientIdCounter = 1; // * +type+ means a Model. /** - The store contains all of the data for records loaded from the server. + The store service contains all of the data for records loaded from the server. It is also responsible for creating instances of `Model` that wrap the individual data for a record, so that they can be bound to in your Handlebars templates. - Define your application's store like this: + By default, applications will have a single `Store` service that is + automatically created. + + The store can be customized by extending the service in the following manner: ```app/services/store.js import Store from '@ember-data/store'; @@ -82,11 +85,8 @@ let globalClientIdCounter = 1; }); ``` - Most Ember.js applications will only have a single `Store` that is - automatically created by their `Ember.Application`. - You can retrieve models from the store in several ways. To retrieve a record - for a specific id, use `Store`'s `findRecord()` method: + for a specific id, use the `Store`'s `findRecord()` method: ```javascript store.findRecord('person', 123).then(function (person) { @@ -112,12 +112,12 @@ let globalClientIdCounter = 1; The store provides multiple ways to create new record objects. They have some subtle differences in their use which are detailed below: - [createRecord](#method_createRecord) is used for creating new + [createRecord](Store/methods/createRecord?anchor=createRecord) is used for creating new records on the client side. This will return a new record in the `created.uncommitted` state. In order to persist this record to the backend, you will need to call `record.save()`. - [push](#method_push) is used to notify Ember Data's store of new or + [push](Store/methods/push?anchor=push) is used to notify Ember Data's store of new or updated records that exist in the backend. This will return a record in the `loaded.saved` state. The primary use-case for `store#push` is to notify Ember Data about record updates (full or partial) that happen @@ -125,7 +125,7 @@ let globalClientIdCounter = 1; [SSE](http://dev.w3.org/html5/eventsource/) or [Web Sockets](http://www.w3.org/TR/2009/WD-websockets-20091222/)). - [pushPayload](#method_pushPayload) is a convenience wrapper for + [pushPayload](Store/methods/pushPayload?anchor=pushPayload) is a convenience wrapper for `store#push` that will deserialize payloads if the Serializer implements a `pushPayload` method. @@ -137,6 +137,7 @@ let globalClientIdCounter = 1; values. @class Store + @main @ember-data/store @extends Ember.Service */ const Store = Service.extend({ @@ -642,12 +643,12 @@ const Store = Service.extend({ }); ``` - See [peekRecord](#method_peekRecord) to get the cached version of a record. + See [peekRecord](Store/methods/peekRecord?anchor=peekRecord) to get the cached version of a record. ### Retrieving Related Model Records If you use an adapter such as Ember's default - [`JSONAPIAdapter`](https://emberjs.com/api/data/classes/DS.JSONAPIAdapter.html) + [`JSONAPIAdapter`](/ember-data/release/classes/JSONAPIAdapter) that supports the [JSON API specification](http://jsonapi.org/) and if your server endpoint supports the use of an ['include' query parameter](http://jsonapi.org/format/#fetching-includes), @@ -1087,7 +1088,7 @@ const Store = Service.extend({ otherwise it will return `null`. A record is available if it has been fetched earlier, or pushed manually into the store. - See [findRecord](#method_findRecord) if you would like to request this record from the backend. + See [findRecord](Store/methods/findRecord?anchor=findRecord) if you would like to request this record from the backend. _Note: This is a synchronous method and does not return a promise._ @@ -1497,7 +1498,7 @@ const Store = Service.extend({ ``` This method returns a promise, which is resolved with an - [`AdapterPopulatedRecordArray`](https://emberjs.com/api/data/classes/DS.AdapterPopulatedRecordArray.html) + [`AdapterPopulatedRecordArray`](/ember-data/release/classes/AdapterPopulatedRecordArray) once the server returns. @since 1.13.0 @@ -1549,7 +1550,7 @@ const Store = Service.extend({ /** This method makes a request for one record, where the `id` is not known - beforehand (if the `id` is known, use [`findRecord`](#method_findRecord) + beforehand (if the `id` is known, use [`findRecord`](Store/methods/findRecord?anchor=findRecord) instead). This method can be used when it is certain that the server will return a @@ -1672,7 +1673,7 @@ const Store = Service.extend({ return promiseObject( _queryRecord(adapter, this, normalizedModelName, query, adapterOptionsWrapper).then(internalModel => { // the promise returned by store.queryRecord is expected to resolve with - // an instance of DS.Model + // an instance of Model if (internalModel) { return internalModel.getRecord(); } @@ -1819,13 +1820,13 @@ const Store = Service.extend({ }); ``` - See [peekAll](#method_peekAll) to get an array of current records in the + See [peekAll](Store/methods/peekAll?anchor=peekAll) to get an array of current records in the store, without waiting until a reload is finished. ### Retrieving Related Model Records If you use an adapter such as Ember's default - [`JSONAPIAdapter`](https://emberjs.com/api/data/classes/DS.JSONAPIAdapter.html) + [`JSONAPIAdapter`](/ember-data/release/classes/JSONAPIAdapter) that supports the [JSON API specification](http://jsonapi.org/) and if your server endpoint supports the use of an ['include' query parameter](http://jsonapi.org/format/#fetching-includes), @@ -1862,7 +1863,7 @@ const Store = Service.extend({ ``` - See [query](#method_query) to only get a subset of records from the server. + See [query](Store/methods/query?anchor=query) to only get a subset of records from the server. @since 1.13.0 @method findAll @@ -1943,7 +1944,7 @@ const Store = Service.extend({ locally created records of the type, however, it will not make a request to the backend to retrieve additional records. If you would like to request all the records from the backend please use - [store.findAll](#method_findAll). + [store.findAll](Store/methods/findAll?anchor=findAll). Also note that multiple calls to `peekAll` for a given type will always return the same `RecordArray`. @@ -2335,7 +2336,7 @@ const Store = Service.extend({ There are some typical properties for `JSONAPI` payload: * `id` - mandatory, unique record's key * `type` - mandatory string which matches `model`'s dasherized name in singular form - * `attributes` - object which holds data for record attributes - `DS.attr`'s declared in model + * `attributes` - object which holds data for record attributes - `attr`'s declared in model * `relationships` - object which must contain any of the following properties under each relationships' respective key (example path is `relationships.achievements.data`): - [`links`](http://jsonapi.org/format/#document-links) - [`data`](http://jsonapi.org/format/#document-resource-object-linkage) - place for primary data @@ -2413,7 +2414,7 @@ const Store = Service.extend({ If you're streaming data or implementing an adapter, make sure that you have converted the incoming data into this form. The - store's [normalize](#method_normalize) method is a convenience + store's [normalize](Store/methods/normalize?anchor=normalize) method is a convenience helper for converting a json payload into the form Ember Data expects. @@ -2692,7 +2693,7 @@ const Store = Service.extend({ /** `normalize` converts a json payload into the normalized form that - [push](#method_push) expects. + [push](Store/methods/push?anchor=push) expects. Example diff --git a/packages/store/addon/-private/system/store/finders.js b/packages/store/addon/-private/system/store/finders.js index d46bec7e9e9..c86c42f7c20 100644 --- a/packages/store/addon/-private/system/store/finders.js +++ b/packages/store/addon/-private/system/store/finders.js @@ -47,7 +47,7 @@ export function _find(adapter, store, modelClass, id, internalModel, options) { ); warn( - `You requested a record of type '${modelName}' with id '${id}' but the adapter returned a payload with primary data having an id of '${payload.data.id}'. Use 'store.findRecord()' when the requested id is the same as the one returned by the adapter. In other cases use 'store.queryRecord()' instead https://emberjs.com/api/data/classes/DS.Store.html#method_queryRecord`, + `You requested a record of type '${modelName}' with id '${id}' but the adapter returned a payload with primary data having an id of '${payload.data.id}'. Use 'store.findRecord()' when the requested id is the same as the one returned by the adapter. In other cases use 'store.queryRecord()' instead.`, coerceId(payload.data.id) === coerceId(id), { id: 'ds.store.findRecord.id-mismatch',