Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
Socket
Sign inDemoInstall
Socket
Sign inDemoInstall

ampersand-collection

Package Overview
Dependencies
Maintainers
4
Versions
45
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

ampersand-collection - npm Package Compare versions

Comparing version 1.3.17 to 1.4.0

.travis.yml

2

ampersand-collection.js

@@ -164,3 +164,3 @@ var BackboneEvents = require('backbone-events-standalone');

var index = this._indexes[indexName || this.mainIndex];
return index[query] || index[query[this.mainIndex]] || this._indexes.cid[query.cid];
return index[query] || index[query[this.mainIndex]] || this._indexes.cid[query] || this._indexes.cid[query.cid];
},

@@ -167,0 +167,0 @@

2

package.json
{
"name": "ampersand-collection",
"version": "1.3.17",
"version": "1.4.0",
"author": "Henrik Joreteg <henrik@andyet.net>",

@@ -5,0 +5,0 @@ "bugs": {

86

README.md

@@ -33,3 +33,3 @@ # ampersand-collection

It emits `add`, `remove` events and makes it possible to merge in a set of objects into an existing collection and emit change events appropriately.
It emits events when models are added, removed, sorted and more. It also allows for merging in a set of objects into an existing collection and emitting change events appropriately. For a detailed overview of the events that are emitted by ampersand-collection, please refer to the [Event Catalog](http://ampersandjs.com/learn/events) on the AmpersandJS learn page.

@@ -71,7 +71,7 @@ If you extend it with a `.model` property that contains a constructor, the collection will ensure that objects that don't match that constructor are instantiated before being added to the collection.

## A quick note about instanceof checks
## A quick note about `instanceof` checks
With npm and browserify for module deps you can sometimes end up with a situation where, the same `collection` constructor wasn't used to build a `collection` object. As a result `instanceof` checks will fail.
Because of module deps in npm and browserify, sometimes it’s possible to end up in a situation where the same `collection` constructor wasn't used to build a `collection` object. As a result, `instanceof` checks will fail.
In order to deal with this (because sometimes this is a legitimate scenario), `collection` simply creates a read-only `isCollection` property on all collection objects that can be used to check whether or a not a given object is in fact a collection object no matter what its constructor was.
To deal with this (because sometimes this is a legitimate scenario), `collection` simply creates a read-only `isCollection` property on all collection objects. You can use it to check whether or a not a given object is, in fact, a collection object—no matter what its constructor was.
<!-- endhide -->

@@ -83,5 +83,5 @@

Create a collection class of your own by extending AmpersandCollection, providing the required instance properties to be attached instances of your class.
Create a collection class of your own by extending `AmpersandCollection`, providing the required instance properties to be attached instances of your class.
Typically you will specify a `model` constructor (if you are storing [ampersand-state](#ampersand-state) or [ampersand-model](#ampersand-model) objects.
Typically you will specify a `model` constructor (if you are storing [ampersand-state](#ampersand-state) or [ampersand-model](#ampersand-model) objects).

@@ -100,3 +100,3 @@ ### model `collection.model`

*Please note* that if you do this, you'll also want to overwrite `isModel` method with your own so you can describe the logic that should be used to determine whether an object is already an instantiated model or not.
*Please note* that if you do this, you'll also want to override the `isModel` method with your own, and describe the logic used to determine whether an object is already an instantiated model or not.

@@ -124,3 +124,3 @@ ```javascript

When creating an AmpersandCollection, you may choose to pass in the initial array of **models**. The collection's [comparator](#comparator) may be included as an option. If you define an **initialize** function, it will be invoked when the collection is created. There are a couple of options that, if provided, are attached to the collection directly: `model`, `comparator` and `parent`.
When creating an `AmpersandCollection`, you may choose to pass in the initial array of **`models`**. The collection's [`comparator`](#comparator) may be included as an option. If you define an **`initialize`** function, it will be invoked when the collection is created. There are a couple of options that, if provided, are attached to the collection directly: `model`, `comparator` and `parent`.

@@ -135,5 +135,5 @@ ```javascript

Specify which property on your models should be used by the collection as the main index and unique identifier for the models/objects it holds. This is the property that [`get`](#ampersand-collection-get) will use to retrieve models by and what `add`, `set`, and `remove` will use to determine whether a model already exists in the collection or not.
Specify which property the collection should use as the main index (and unique identifier) for the models/objects it holds. This is the property that [`get`](#ampersand-collection-get) uses to retrieve models, and what `add`, `set`, and `remove` uses to determine whether a collection already contains a model or not.
If you specify a [`model`](http://ampersandjs.com/docs#ampersand-collection-model) property in the collection and that model specifies an [`idAttribute`](http://ampersandjs.com/docs#ampersand-state-idattribute) the collection will use *that* as the `mainIndex` unless you set it to something else explicitly.
If you specify a [`model`](http://ampersandjs.com/docs#ampersand-collection-model) property in the collection, and the model specifies an [`idAttribute`](http://ampersandjs.com/docs#ampersand-state-idattribute), the collection will use *that* as the `mainIndex` unless you explicitly set it to something else.

@@ -144,3 +144,3 @@ If *no* `mainIndex` or `model` is specified `"id"` is used as the default `mainIndex`.

But if you wish, you may set it while extending AmpersandCollection like so:
But if you wish, you may set it while extending `AmpersandCollection` like so:

@@ -155,3 +155,3 @@ ```javascript

Specify an optional array of keys by which to additionally index the models in your collection (in addition to the `mainIndex`. This allows you to quickly retrieve models by specifying the key to use with [get](#ampersand-collection-get).
Specify an optional array of keys to serve as additional indexes for the models in your collection (in addition to `mainIndex`). This allows you to quickly retrieve models by specifying the key to use with [`get`](#ampersand-collection-get).

@@ -182,14 +182,15 @@ Note that `get` will only ever return a single model, so the values of these indexes should be unique across the models in the collection:

Returns the length of the underlying array.
Returns the `length` of the underlying array.
### isCollection/instanceof `collection.isCollection`
With npm and browserify for module deps you can sometimes end up with a situation where, the same `collection` constructor wasn't used to build a `collection` object. As a result `instanceof` checks will fail.
In order to deal with this (because sometimes this is a legitimate scenario), `collection` simply creates a read-only `isCollection` property on all collection objects that can be used to check whether or a not a given object is in fact a collection object no matter what its constructor was.
Because of module deps in npm and browserify, sometimes it’s possible to end up in a situation where the same `collection` constructor wasn't used to build a `collection` object. As a result, `instanceof` checks will fail.
To deal with this (because sometimes this is a legitimate scenario), `collection` simply creates a read-only `isCollection` property on all collection objects. You can use it to check whether or a not a given object is, in fact, a collection object—no matter what its constructor was.
### add `collection.add(modelOrObject, [options])`
Add a model (or an array of models) to the collection, firing an `"add"` event. If a [model](#ampersand-collection-model) property is defined, you may also pass raw attributes objects, and have them be vivified as instances of the model. Returns the added (or preexisting, if duplicate) models.
Add a model (or an array of models) to the collection, firing an `"add"` event. If a [`model`](#ampersand-collection-model) property is defined, you may also pass raw attributes objects, and have them be vivified as instances of the model. Returns the added models (or preexisting models, if already contained).

@@ -199,3 +200,3 @@ **Options:**

* Pass `{at: index}` to splice the model into the collection at the specified index.
* If you're adding models to the collection that are already in the collection, they'll be ignored, unless you pass `{merge: true}`, in which case their attributes will be merged into the corresponding models, firing any appropriate `"change"` events.
* If you're adding models to the collection that it already contains, they'll be ignored, unless you pass `{merge: true}`, in which case their attributes will be merged into the corresponding models, firing any appropriate `"change"` events.

@@ -219,3 +220,3 @@ ```javascript

Note that adding the same model (a model with the same id) to a collection more than once is a no-op.
Note that adding the same model (a model with the same `id`) to a collection more than once is a no-op.

@@ -225,7 +226,7 @@

Serialize the collection into a plain javascript array, ready for sending to the server (typically called via [toJSON](#ampersand-collection-tojson)). Will also call `serialize()` on each model in the collection.
Serialize the collection into a plain javascript array, ready for sending to the server (typically called via [`toJSON`](#ampersand-collection-tojson)). Also calls `serialize()` on each model in the collection.
### toJSON `collection.toJSON()`
Returns a plain javascript array of the models in the collection (which are also serialized) ready for sending to the server. The name of this method is a bit confusing, as it doesn't actually return a JSON string — but I'm afraid that it's the way that the JavaScript API for JSON.stringify works.
Returns a plain javascript array of the models in the collection (which are also serialized), ready for sending to the server. The name of this method is a bit confusing, as it doesn't actually return a JSON string — but I'm afraid that it's the way that the JavaScript API for `JSON.stringify()` works.

@@ -246,4 +247,12 @@ ```javascript

The **set** method performs a "smart" update of the collection with the passed list of models. If a model in the list isn't yet in the collection it will be added; if the model is already in the collection its attributes will be merged; and if the collection contains any models that aren't present in the list, they'll be removed. All of the appropriate `"add"`, `"remove"`, and `"change"` events are fired as this happens. Returns the touched models in the collection. If you'd like to customize the behavior, you can disable it with options: `{add: false}`, `{remove: false}`, or `{merge: false}`.
The **set** method performs a "smart" update of the collection with the passed list of models:
* If a model in the list isn't in the collection, it will be added.
* If a model in the list is in the collection already, its attributes will be merged.
* If the collection contains any models that aren't in the list, they'll be removed.
All of the appropriate `"add"`, `"remove"`, and `"change"` events are fired as this happens. If you'd like to customize the behavior, you can disable it with options: `{add: false}`, `{remove: false}`, or `{merge: false}`.
Returns the touched models in the collection.
```javascript

@@ -263,5 +272,5 @@ var vanHalen = new AmpersandCollection([eddie, alex, stone, roth]);

With an unspecified `indexName` (`collection.get(123)`) retrieves the model by it's [mainIndex](#ampersand-collection-mainindex) attribute.
If called without `indexName` (`collection.get(123)`), retrieves the model by its [`mainIndex`](#ampersand-collection-mainindex) attribute.
Or specify an `indexName` to retrieve a model by any of the other listed [indexes](#ampersand-collection-indexes).
Alternatively, specify an `indexName` to retrieve a model by any of the other listed [`indexes`](#ampersand-collection-indexes).

@@ -290,11 +299,11 @@ ```javascript

Get a model from a collection, specified by index. Useful if your collection is sorted, and if your collection isn't sorted, at will still retrieve models in insertion order.
Get a model from a collection, specified by `index`. Useful if your collection is sorted.
e.g. `collection.at(0)` returns the first model in the collection.
If your collection isn't sorted, `at()` will still retrieve models in insertion order; e.g., `collection.at(0)` returns the first model in the collection.
### remove `collection.remove(models, [options])`
Remove a model (or an array of models) from the collection, and returns them. Fires a `"remove"` event, which you can use `{ silent: true }` to suppress. The model's index before removal is available to listeners as `options.index`.
Remove a model (or an array of models) from the collection, and returns them. Fires a `"remove"` event, which you can use the option `{ silent: true }` to suppress. The model's index before removal is available to listeners as `options.index`.
The models object/array can be references to actual models, or just a list of ids to remove.
The models object/array can be references to actual models, or just a list of `id`s to remove.

@@ -304,4 +313,6 @@

Adding and removing models one at a time is all well and good, but sometimes you have so many models to change that you'd rather just update the collection in bulk. Use **reset** to replace a collection with a new list of models (or attribute hashes), triggering a single `"reset"` event at the end. Returns the newly-set models. For convenience, within a `"reset"` event, the list of any previous models is available as `options.previousModels`.
Adding and removing models one at a time is all well and good, but sometimes there are so many models to change that you'd rather just update the collection in bulk. Use **`reset()`** to replace a collection with a new list of models (or attribute hashes), triggering a single `"reset"` event at the end. For convenience, within a `"reset"` event, the list of any previous models is available as `options.previousModels`.
Returns the newly-set models.
Calling `collection.reset()` without passing any models as arguments will empty the entire collection.

@@ -311,5 +322,7 @@

Force a collection to re-sort itself. You don't need to call this under normal circumstances, as a collection with a comparator will sort itself whenever a model is added. To disable sorting when adding a model, pass `{sort: false}` to add. Calling sort triggers a `"sort"` event on the collection.
Force a collection to re-sort itself. Triggers a `"sort"` event on the collection.
You don't need to call this under normal circumstances, as a collection with a `comparator` will sort itself whenever a model is added. To prevent this when adding a model, pass a `{sort: false}` option to `add()`.
### models `collection.models`

@@ -321,11 +334,11 @@

Comparator option lets you define how models within a given collection will be sorted. There're a few ways to declare your comparator:
The `comparator` option lets you define how models in a collection are sorted. There's a few ways to declare `comparator`:
* Passing `false` will prevent sorting
* Passing `string` will sort collection by a specific model attribute
* Passing `function` will use native array sort function, which you can define with either 1 argument (each model one by one) or more, which lets you write custom compare functions with next 2 models as arguments
* Passing `false` prevents sorting
* Passing `string` sorts the collection by a specific model attribute
* Passing `function` will use native array `sort` function; which you can define with either 1 argument (each model one by one), or multiple arguments (which lets you write custom compare functions with next 2 models as arguments).
### proxied ES5 array methods (9)
The base AmpersandCollection proxies some basic ES5 methods to the underlying model array. Further documentation of these methods is available at [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array#Iteration_methods)
The base `AmpersandCollection` proxies some basic ES5 methods to the underlying model array. Further documentation of these methods is available at [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array#Iteration_methods)

@@ -343,3 +356,3 @@ * indexOf

Unlike a backbone collection it does not include underscore and all the array methods from underscore, though if you wish more functions than those built into modern browsers, you can mixin [ampersand-collection-underscore-mixin](https://github.com/AmpersandJS/ampersand-collection-underscore-mixin) to get them.
Unlike Backbone collections, it does not include Underscore and all of its array methods. But if you want more functions than those built into modern browsers, you can mixin [`ampersand-collection-underscore-mixin`](https://github.com/AmpersandJS/ampersand-collection-underscore-mixin) to get them.

@@ -361,2 +374,3 @@ ```javascript

<!-- starthide -->

@@ -366,3 +380,3 @@

Created by [@HenrikJoreteg](http://twitter.com/henrikjoreteg) but many ideas and some code (especially for the `set`) methods should be credited to Jeremy Ashkenas and the rest of the Backbone.js authors.
Created by [@HenrikJoreteg](http://twitter.com/henrikjoreteg), but many ideas and some code (especially for `set()`) should be credited to Jeremy Ashkenas and the rest of the Backbone.js authors.

@@ -369,0 +383,0 @@

19

test/main.js

@@ -368,1 +368,20 @@ var test = require('tape');

});
test('get can be used with cid value or cid obj', function (t) {
t.plan(2);
var C = Collection.extend({
model: State.extend({
props: {
id: 'number'
}
})
});
var collection = new C([{id: 1}, {id: 2}, {id: 3}]);
var first = collection.at(0);
t.equal(1, collection.get(first.cid).id);
t.equal(1, collection.get({cid: first.cid}).id);
t.end();
});
SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

About

Packages

npm

Go

Maven

PyPI

Rubygems

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc