{ "_args": [ [ { "raw": "ember-ajax@^3.0.0", "scope": null, "escapedName": "ember-ajax", "name": "ember-ajax", "rawSpec": "^3.0.0", "spec": ">=3.0.0 <4.0.0", "type": "range" }, "/home/travis/build/lukesargeant/ember-sparkline" ] ], "_from": "ember-ajax@>=3.0.0 <4.0.0", "_id": "ember-ajax@3.0.0", "_inCache": true, "_location": "/ember-ajax", "_nodeVersion": "6.7.0", "_npmOperationalInternal": { "host": "packages-12-west.internal.npmjs.com", "tmp": "tmp/ember-ajax-3.0.0.tgz_1492897092175_0.029822104144841433" }, "_npmUser": { "name": "alexlafroscia", "email": "alex@lafroscia.com" }, "_npmVersion": "3.10.3", "_phantomChildren": {}, "_requested": { "raw": "ember-ajax@^3.0.0", "scope": null, "escapedName": "ember-ajax", "name": "ember-ajax", "rawSpec": "^3.0.0", "spec": ">=3.0.0 <4.0.0", "type": "range" }, "_requiredBy": [ "#DEV:/" ], "_resolved": "https://registry.npmjs.org/ember-ajax/-/ember-ajax-3.0.0.tgz", "_shasum": "8f21e9da0c1d433cf879aa855fce464d517e9ab5", "_shrinkwrap": null, "_spec": "ember-ajax@^3.0.0", "_where": "/home/travis/build/lukesargeant/ember-sparkline", "bugs": { "url": "https://github.com/ember-cli/ember-ajax/issues" }, "dependencies": { "ember-cli-babel": "^6.0.0" }, "description": "Service for making AJAX requests in Ember 1.13+ applications.", "devDependencies": { "broccoli-asset-rev": "^2.4.5", "coveralls": "^2.13.0", "ember-cli": "^2.12.2", "ember-cli-chai": "^0.3.2", "ember-cli-code-coverage": "^0.3.12", "ember-cli-dependency-checker": "^1.4.0", "ember-cli-eslint": "3.0.3", "ember-cli-htmlbars": "^1.3.0", "ember-cli-htmlbars-inline-precompile": "^0.4.0", "ember-cli-inject-live-reload": "^1.4.1", "ember-cli-mocha": "^0.13.3", "ember-cli-pretender": "^1.0.1", "ember-cli-release": "^1.0.0-beta.2", "ember-cli-shims": "1.1.0", "ember-cli-sri": "^2.1.0", "ember-cli-test-loader": "^2.1.0", "ember-cli-testdouble": "0.1.0", "ember-cli-uglify": "^1.2.0", "ember-data": "^2.12.2", "ember-disable-prototype-extensions": "^1.1.0", "ember-export-application-global": "2.0.0", "ember-load-initializers": "1.0.0", "ember-resolver": "4.1.0", "ember-source": "^2.12.1", "eslint": "^3.19.0", "eslint-plugin-ember-suave": "^1.0.0", "loader.js": "^4.3.0", "testdouble-chai": "^0.5.0" }, "directories": { "doc": "doc", "test": "tests" }, "dist": { "shasum": "8f21e9da0c1d433cf879aa855fce464d517e9ab5", "tarball": "https://registry.npmjs.org/ember-ajax/-/ember-ajax-3.0.0.tgz" }, "ember-addon": { "configPath": "tests/dummy/config" }, "engines": { "node": ">= 4" }, "gitHead": "2aba19ed7c9f1771994895237c7b20ca52165871", "homepage": "https://github.com/ember-cli/ember-ajax#readme", "keywords": [ "ember-addon" ], "license": "MIT", "maintainers": [ { "name": "alexlafroscia", "email": "alex@lafroscia.com" }, { "name": "taras", "email": "tarasm@gmail.com" } ], "name": "ember-ajax", "optionalDependencies": {}, "readme": "# ember-ajax\n\n[![Travis CI Build Status](https://travis-ci.org/ember-cli/ember-ajax.svg?branch=master)](https://travis-ci.org/ember-cli/ember-ajax)\n[![Coverage Status](https://coveralls.io/repos/github/ember-cli/ember-ajax/badge.svg?branch=master)](https://coveralls.io/github/ember-cli/ember-ajax?branch=master)\n[![Ember Observer Score](http://emberobserver.com/badges/ember-ajax.svg)](http://emberobserver.com/addons/ember-ajax)\n![Ember Version][ember-version]\n\nService for making AJAX requests in Ember 1.13+ applications.\n\n* customizable service\n* returns RSVP promises\n* improved error handling\n* ability to specify request headers\n* upgrade path from `ic-ajax`\n\n## Getting started\n\nTo use the ajax service, inject the `ajax` service into your route or component.\n\n```js\nimport Ember from 'ember';\n\nexport default Ember.Route.extend({\n ajax: Ember.inject.service(),\n model() {\n return this.get('ajax').request('/posts');\n }\n});\n```\n\n## Ajax Service\n\n### Basic Usage\n\nThe AJAX service provides methods to be used to make AJAX requests, similar to\nthe way that you would use `jQuery.ajax`. In fact, `ember-ajax` is a wrapper\naround jQuery's method, and can be configured in much the same way.\n\nIn general, you will use the `request(url, options)` method, where `url` is the\ndestination of the request and `options` is a configuration hash for\n[`jQuery.ajax`](http://api.jquery.com/jQuery.ajax/#jQuery-ajax-settings).\n\n```javascript\nimport Ember from 'ember';\n\nexport default Ember.Controller.extend({\n ajax: Ember.inject.service(),\n actions: {\n sendRequest() {\n return this.get('ajax').request('/posts', {\n method: 'POST',\n data: {\n foo: 'bar'\n }\n });\n }\n }\n});\n```\n\nIn this example, `this.get('ajax').request()` will return a promise with the\nresult of the request. Your handler code inside `.then` or `.catch` will\nautomatically be wrapped in an Ember run loop for maximum compatibility with\nEmber, right out of the box.\n\n### HTTP-verbed methods\n\nYou can skip setting the `method` or `type` keys in your `options` object when\ncalling `request(url, options)` by instead calling `post(url, options)`,\n`put(url, options)`, `patch(url, options)` or `del(url, options)`.\n\n```js\npost('/posts', { data: { title: 'Ember' } }) // Makes a POST request to /posts\nput('/posts/1', { data: { title: 'Ember' } }) // Makes a PUT request to /posts/1\npatch('/posts/1', { data: { title: 'Ember' } }) // Makes a PATCH request to /posts/1\ndel('/posts/1') // Makes a DELETE request to /posts/1\n```\n\n### Custom Request Headers\n\n`ember-ajax` allows you to specify headers to be used with a request. This is\nespecially helpful when you have a session service that provides an auth token\nthat you have to include with the requests to authorize your requests.\n\nTo include custom headers to be used with your requests, you can specify\n`headers` hash on the `Ajax Service`.\n\n```js\n// app/services/ajax.js\n\nimport Ember from 'ember';\nimport AjaxService from 'ember-ajax/services/ajax';\n\nexport default AjaxService.extend({\n session: Ember.inject.service(),\n headers: Ember.computed('session.authToken', {\n get() {\n let headers = {};\n const authToken = this.get('session.authToken');\n if (authToken) {\n headers['auth-token'] = authToken;\n }\n return headers;\n }\n })\n});\n```\n\nHeaders by default are only passed if the hosts match, or the request is a relative path.\nYou can overwrite this behavior by either passing a host in with the request, setting the\nhost for the ajax service, or by setting an array of `trustedHosts` that can be either\nan array of strings or regexes.\n\n```js\n// app/services/ajax.js\n\nimport Ember from 'ember';\nimport AjaxService from 'ember-ajax/services/ajax';\n\nexport default AjaxService.extend({\n trustedHosts: [\n /\\.example\\./,\n 'foo.bar.com',\n ]\n});\n```\n\n\n### Custom Endpoint Path\n\nThe `namespace` property can be used to prefix requests with a specific url namespace.\n\n```js\n// app/services/ajax.js\n\nimport Ember from 'ember';\nimport AjaxService from 'ember-ajax/services/ajax';\n\nexport default AjaxService.extend({\n namespace: '/api/v1'\n});\n```\n\n`request('/users/me')` would now target `/api/v1/users/me`\n\n### Custom Host\n\n`ember-ajax` allows you to specify a host to be used with a request. This is\nespecially helpful so you don't have to continually pass in the host along\nwith the path, makes `request()` a bit cleaner.\n\nTo include a custom host to be used with your requests, you can specify `host`\nproperty on the `Ajax Service`.\n\n```js\n// app/services/ajax.js\n\nimport Ember from 'ember';\nimport AjaxService from 'ember-ajax/services/ajax';\n\nexport default AjaxService.extend({\n host: 'http://api.example.com'\n});\n```\n\nThat allows you to only have to make a call to `request()` as such:\n\n```js\n// GET http://api.example.com/users/me\nrequest('/users/me')\n```\n\nYou can even leave off the forward slash if you'd like:\n```js\n// GET http://api.example.com/users/me\nrequest('users/me')\n```\n\n### Custom Content-Type\n\n`ember-ajax` allows you to specify a default [Content-Type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type) header to be used with a request.\n\nTo include a custom Content-Type you can specify `contentType` property on the `Ajax Service`.\n\n```js\n// app/services/ajax.js\n\nimport Ember from 'ember';\nimport AjaxService from 'ember-ajax/services/ajax';\n\nexport default AjaxService.extend({\n contentType: 'application/json; charset=utf-8'\n});\n```\n\nYou can also override the Content-Type per `request` with the `options` parameter.\n\n#### Customize isSuccess\n\nSome APIs respond with status code 200, even though an error has occurred and\nprovide a status code in the payload. With the service, you can easily account\nfor this behaviour by overwriting the `isSuccess` method.\n\n```js\n// app/services/ajax.js\n\nimport AjaxService from 'ember-ajax/services/ajax';\n\nexport default AjaxService.extend({\n isSuccess(status, headers, payload ) {\n let isSuccess = this._super(...arguments);\n if (isSuccess && payload.status) {\n // when status === 200 and payload has status property,\n // check that payload.status is also considered a success request\n return this._super(payload.status);\n }\n return isSuccess;\n }\n});\n```\n\n### Error handling\n\n`ember-ajax` provides built in error classes that you can use to check the error\nthat was returned by the response. This allows you to restrict determination of\nerror result to the service instead of sprinkling it around your code.\n\n#### Built in error types\n\n`ember-ajax` has built-in error types that will be returned from the service in the event of an error:\n\n* `BadRequestError` (400)\n* `UnauthorizedError`(401)\n* `ForbiddenError`(403)\n* `NotFoundError` (404)\n* `InvalidError`(422)\n* `ServerError` (5XX)\n* `AbortError`\n* `TimeoutError`\n\nAll of the above errors are subtypes of `AjaxError`.\n\n#### Error detection helpers\n\n`ember-ajax` comes with helper functions for matching response errors to their respective `ember-ajax` error type. Each of the errors listed above has a corresponding `is*` function (e.g., `isBadRequestError`).\n\nUse of these functions is **strongly encouraged** to help eliminate the need for boilerplate error detection code.\n\n```js\nimport Ember from 'ember';\nimport {isAjaxError, isNotFoundError, isForbiddenError} from 'ember-ajax/errors';\n\nexport default Ember.Route.extend({\n ajax: Ember.inject.service(),\n model() {\n const ajax = this.get('ajax');\n\n return ajax.request('/user/doesnotexist')\n .catch(function(error) {\n if (isNotFoundError(error)) {\n // handle 404 errors here\n return;\n }\n\n if (isForbiddenError(error)) {\n // handle 403 errors here\n return;\n }\n\n if(isAjaxError(error)) {\n // handle all other AjaxErrors here\n return;\n }\n\n // other errors are handled elsewhere\n throw error;\n });\n }\n});\n```\n\nIf your errors aren't standard, the helper function for that error type can be used as the base to build your custom detection function.\n\n#### Access the response in case of error\n\nIf you need to access the json response of a request that failed, you can use the `raw` method instead of `request`.\n\n```js\nthis.get('ajax').raw(url, options)\n .then(({ response }) => this.handleSuccess(response))\n .catch(({ response, jqXHR, payload }) => this.handleError(response));\n```\n\nNote that in this use case there's no access to the error object. You can inspect the `jqXHR` object for additional information about the failed request. In particular `jqXHR.status` returns the relevant HTTP error code.\n\n## Usage with Ember Data\n\nEmber AJAX provides a mixin that can be used in an Ember Data Adapter to avoid the networking code provided by Ember Data and rely on Ember AJAX instead. This serves as a first step toward true integration of Ember AJAX into Ember Data.\n\nTo use the mixin, you can include the mixin into an Adapter, like so:\n\n```javascript\n// app/adapters/application.js\nimport DS from 'ember-data';\nimport AjaxServiceSupport from 'ember-ajax/mixins/ajax-support';\n\nexport default DS.JSONAPIAdapter.extend(AjaxServiceSupport);\n```\n\nThat's all the configuration required! If you want to customize the adapter, such as using an alternative AJAX service (like one you extended yourself), hooks to do so are provided; check out the mixin's implementation for details.\n\nNote that instead of using the Ember Data error checking code in your application, you should use the ones provided by Ember AJAX.\n\n## Stand-Alone Usage\n\nIf you aren't using Ember Data and do not have access to services, you\ncan import the ajax utility like so:\n\n```js\nimport request from 'ember-ajax/request';\n\nexport default function someUtility(url) {\n var options = {\n // request options\n };\n\n return request(url, options).then(response => {\n // `response` is the data from the server\n return response;\n });\n}\n```\n\nWhich will have the same API as the `ajax` service. If you want the raw jQuery XHR object\nthen you can use the `raw` method instead:\n\n```js\nimport raw from 'ember-ajax/raw';\n\nexport default function someOtherUtility(url) {\n var options = {\n // raw options\n };\n\n return raw(url, options).then(result => {\n // `result` is an object containing `response` and `jqXHR`, among other items\n return result;\n });\n}\n```\n\n## Testing\n\n### Fixture Data\n\nWhen writing tests, you will often need to provide fixture data for your\napplication. This can be accomplished by mocking your server with\n[`Pretender.js`](https://github.com/pretenderjs/pretender). You can use it\ndirectly with [ember-cli-pretender](https://github.com/rwjblue/ember-cli-pretender)\nor through a helper library.\n\nIf you're looking for a full featured mock server with fixtures support, choose\n[EmberCLI Mirage](http://www.ember-cli-mirage.com/) otherwise use the leaner\n[EmberCLI Fake Server](https://github.com/201-created/ember-cli-fake-server).\n\n#### Error Handling\n\nWhen writing integration & acceptance tests, your tests should be testing for\nwhat the user can see. Therefore, your tests should be checking if the errors\nare in the DOM. If errors bubble up to the console, then you should catch the\nfailure in your app code and present the errors to the user.\n\n### Acceptance Tests\n\n```javascript\nimport { test } from 'qunit';\nimport moduleForAcceptance from 'dummy/tests/helpers/module-for-acceptance';\n\nimport Pretender from 'pretender';\n\nlet server;\n\nmoduleForAcceptance('ajax-get component', {\n beforeEach() {\n server = new Pretender();\n },\n afterEach() {\n server.shutdown();\n }\n});\n\ntest('waiting for a route with async widget', function(assert) {\n\n const PAYLOAD = [{ title: 'Foo' }, { title: 'Bar' }, { title: 'Baz' }];\n\n server.get('/posts', function(){\n return [ 200, {\"Content-Type\": \"application/json\"}, JSON.stringify(PAYLOAD) ];\n }, 300);\n\n visit('/');\n\n andThen(function() {\n assert.equal(currentURL(), '/');\n assert.ok($('.ajax-get').length === 1, 'ajax-get component is rendered');\n });\n\n click('button:contains(Load Data)');\n\n andThen(function(){\n assert.equal($('.ajax-get li:eq(0)').text(), 'Foo');\n assert.equal($('.ajax-get li:eq(1)').text(), 'Bar');\n assert.equal($('.ajax-get li:eq(2)').text(), 'Baz');\n });\n});\n```\n\n### Integration Test\n\n```javascript\nimport hbs from 'htmlbars-inline-precompile';\nimport {\n moduleForComponent,\n test\n} from 'ember-qunit';\n\nimport Pretender from 'pretender';\nimport json from 'dummy/tests/helpers/json';\nimport wait from 'ember-test-helpers/wait';\n\nlet server;\nmoduleForComponent('ajax-get', {\n integration: true,\n beforeEach() {\n server = new Pretender();\n },\n afterEach() {\n server.shutdown();\n }\n});\n\ntest('clicking Load Data loads data', function(assert) {\n const PAYLOAD = [{ title: 'Foo' }, { title: 'Bar' }, { title: 'Baz' }];\n\n server.get('/foo', json(200, PAYLOAD), 300);\n\n this.render(hbs`\n {{#ajax-get url=\"/foo\" as |data isLoaded|}}\n {{#if isLoaded}}\n \n {{else}}\n \n {{/if}}\n {{/ajax-get}}\n `);\n\n this.$(`.ajax-get button`).click();\n\n return wait().then(function(){\n assert.equal($('.ajax-get li:eq(0)').text(), 'Foo');\n assert.equal($('.ajax-get li:eq(1)').text(), 'Bar');\n assert.equal($('.ajax-get li:eq(2)').text(), 'Baz');\n });\n});\n```\n\n**Notice**, the `wait()` helper. It waits for Ajax requests to complete before\ncontinuing.\n\n## Upgrade from `ic-ajax`\n\nThis addon was written to supersede `ic-ajax` and `ember-cli-ic-ajax` addon\nbecause `ic-ajax` includes features and practices that are no longer considered\nbest practices.\n\nIn most cases, it should be fairly easy to upgrade to `ember-ajax`. To aid\nyou in the migration process, I would recommend that you follow the following\nsteps.\n\n1. Install `ember-ajax` with `ember install ember-ajax`\n2. Search and replace `ic-ajax` with `ember-ajax`\n3. Run your test suite and look for `ic-ajax` related deprecations\n4. Refactor your code to eliminate the deprecations.\n5. Uninstall `ic-ajax` with `npm uninstall --save-dev ember-cli-ic-ajax`\n\nHere is a list of notable changes that you need to consider when refactoring.\n\n* `ic-ajax` is used by importing `ic-ajax` into a module. `ember-ajax` is used\n by injecting `ajax` service into a route or component.\n* `ic-ajax` error handler returns a hash with { jqXHR, textStatus, errorThrown }.\n `ember-ajax` returns an error object that's an instance of `AjaxError`. `error`\n object will be either `AjaxError` with `error.status` or one of the error\n types listed above.\n* When you `import ajax from 'ic-ajax'`, `ajax` function will resolve to\n payload, same way as `ajax.request`. `import raw from 'ic-ajax/raw'`\n resolves to raw `jqXHR` object with payload on `response` property.\n\n## Installation\n\n### As an addon\n\n* `ember install ember-ajax`\n\n### For development\n\n* `git clone` this repository\n* `npm install`\n* `bower install`\n\n## Running\n\n* `ember server`\n* Visit your app at http://localhost:4200.\n\n## Running Tests\n\n* `ember test`\n* `ember test --server`\n\n## Building\n\n* `ember build`\n\nFor more information on using ember-cli, visit [http://www.ember-cli.com/](http://www.ember-cli.com/).\n\n## Why an Ajax Service?\n\nWe need a singleton mechanism for making Ajax requests because currently many\nEmber applications have at least two ways to talk to backend APIs. With Ember\nData, `RESTAdapter#ajax` offers the ability to specify custom headers and good\nerror reporting. When making requests that don't require Ember Data, getting\nthe same features is difficult because `ic-ajax` and `Ember.$.ajax` don't offer\nany interfaces that can automatically set headers based on property of\nanother service (like a session service).\n\nThe idea with this addon is to provide a service that can be used by both\nEmber Data and on ad-hoc bases and provides consistent interface for making\nAjax requests.\n\n## Special Thanks\n\nThis addon was based on ajax handing in Ember Data's Adapter.\n\n[ember-version]: https://embadge.io/v1/badge.svg?start=1.13.0\n", "readmeFilename": "README.md", "repository": { "url": "git+ssh://git@github.com/ember-cli/ember-ajax.git", "type": "git" }, "scripts": { "build": "ember build", "start": "ember server", "test": "ember try:each" }, "version": "3.0.0" }