Merge pull request #21 from RoundingWellOS/v2

feat(store): add v2 cache primitives

Author: paulfalgout

.babelrc

@@ -0,0 +1 @@
+24

.eslintrc

@@ -1,3 +1,5 @@
 language: node_js
 node_js:
-  - "12.0"
+  - "24"
+script:
+  - npm run check

.nvmrc

@@ -0,0 +1,19 @@
+# Changelog
+
+## 2.0.0
+
+- Add synchronous cache primitives: `find`, `has`, `patch`, `evict`, `inspect`, `reset`, and `resetAll`.
+- Ship TypeScript declarations for the public Store and ModelCache APIs.
+- Modernize package output to ESM (`dist/backbone.store.mjs`), CJS (`dist/backbone.store.cjs`), and UMD (`dist/backbone.store.js`) through an `exports` map.
+- Add `"type": "module"` for native ESM source and tooling.
+- Change raw CommonJS consumption to use the default export: `require('backbone.store').default`.
+- Remove the old `dist/backbone.store.esm.js` filename; use `dist/backbone.store.mjs` or the package root import instead.
+- Keep UMD assignment on `Backbone.Store` without adding a `window.Store` global.
+- Upgrade the test/build stack for Node 24 and replace Babel/Rollup/nyc with native ESM, tsdown, ESLint flat config, and c8.
+
+### Fixes
+
+- Prevent id-key collisions for ids such as `"toString"` and `"__proto__"` by using null-prototype cache storage.
+- Track pending no-id models so Store-owned listeners are cleaned up if the model is reset, removed, or destroyed before receiving an id.
+- Detach Store-owned `destroy` listeners when `Store.remove(modelName)`, `Store.removeAll()`, `Store.reset(modelName)`, or `Store.resetAll()` clears cached instances.
+- Avoid object-inspection conflicts when assertion/debug tools call `Store.inspect(depth, options)` while formatting Store references.

.travis.yml

@@ -65,14 +65,49 @@ Returns all `ModelCache` instances by name.
 #### `Store.get(modelName)`
 Returns a Model definition by name.
 
+#### `Store.find(modelName, id)`
+Returns a cached model instance by id, or `undefined` if the model is not cached.
+The id is normalized with `String(id)`, so `1` and `"1"` resolve to the same cached model.
+`null` and `undefined` ids return `undefined`.
+
+#### `Store.has(modelName, id)`
+Returns `true` when a model instance is cached by id.
+`null` and `undefined` ids return `false`.
+
+#### `Store.patch(modelName, id, attrs, [options])`
+Updates an existing cached model with `model.set(attrs, options)`.
+Returns the patched model, or `undefined` when the id is not cached.
+This is the option-aware update API; duplicate construction still preserves the original behavior and calls `set(attrs)` without options.
+
+#### `Store.evict(modelName, id)`
+Removes one cached model without destroying it.
+Returns the evicted model, or `undefined` when the id is not cached.
+This triggers the Store `remove` event for the evicted model.
+
+#### `Store.inspect(modelName, id)`
+Returns `{ modelName, id, key, cached, model }`.
+`id` is the caller-supplied id, `key` is the normalized cache key, and `model` is the live Backbone model reference or `undefined`.
+For `null` and `undefined` ids, `key` is `undefined`, `cached` is `false`, and `model` is `undefined`.
+When called by object-formatting tools as `.inspect(depth, options)`, returns a short Store label instead of treating `depth` as a model name.
+
 #### `Store.getAll()`
 Returns all Model definitions by name.
 
+#### `Store.reset(modelName)`
+Clears all cached and pending models for one `modelName` while keeping the registered Model definition.
+This detaches Store-owned listeners and does not trigger `remove` or `reset` events.
+
+#### `Store.resetAll()`
+Clears all cached and pending models for every registered Model definition.
+This keeps the registered Model definitions and does not trigger `remove` or `reset` events.
+
 #### `Store.remove(modelName)`
 Removes a `ModelCache` from `Store` by name.
+This detaches Store-owned listeners and does not trigger `remove` or `reset` events.
 
 #### `Store.removeAll()`
 Removes the entire cache.
+This detaches Store-owned listeners and does not trigger `remove` or `reset` events.
 
 #### `Store` examples
 ```javscript
@@ -93,6 +128,9 @@ const Models = Store.getAll();
 console.log(StoredModel === Models.myModel.modelConstructor);
 ```
 
+All APIs that take `modelName` throw the same error as `Store.getCache(modelName)` when the model name is not recognized.
+Calling `StoredModel.extend(...)` still delegates to Backbone's inherited `extend`; the returned child constructor is not automatically registered with Store unless it is passed through `Store(childModel, modelName)`.
+
 ### Store Events
 
 #### `add`
@@ -165,11 +203,15 @@ Instances will have four properties:
 #### `get(attrs, options)`
 If the instance by index is not cached it is instantiated, cached, and returned.
 Otherwise it returns the cached instance and sets the `attrs` on the model.
-The `options` passed to this method will pass through to the `new` or the `set`.
+The `options` passed to this method will pass through only when a new model is instantiated.
+Use `patch(id, attrs, options)` when cached updates need `set` options.
 
 #### `remove(instance)`
 Removes the model instance from the cache.
 
+#### `find(id)`, `has(id)`, `patch(id, attrs, [options])`, `evict(id)`, `inspect(id)`, `reset()`
+ModelCache-level primitives backing the Store APIs of the same names.
+
 ## Acknowledgments
 
 Backbone.Store is heavily inspired by [Backbone.UniqueModel](https://github.com/disqus/backbone.uniquemodel) written by [Ben Vinegar](http://github.com/benvinegar)

CHANGELOG.md

@@ -0,0 +1,238 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+let underscore = require("underscore");
+let backbone = require("backbone");
+backbone = __toESM(backbone, 1);
+//#region lib/model-cache.js
+function createCache() {
+	return Object.create(null);
+}
+function ModelCache(Model, modelName) {
+	this.instances = createCache();
+	this.pending = [];
+	this.Model = Model;
+	this.modelName = modelName;
+	this.ModelConstructor = this._getConstructor(Model);
+}
+(0, underscore.extend)(ModelCache.prototype, {
+	_getConstructor(Model) {
+		const cache = this;
+		const ModelConstructor = function(attrs, options) {
+			return cache.get(attrs, options);
+		};
+		(0, underscore.extend)(ModelConstructor, Model);
+		ModelConstructor.prototype = this.Model.prototype;
+		return ModelConstructor;
+	},
+	get(attrs, options) {
+		const instanceKey = this._getKey(attrs);
+		const instance = this.find(instanceKey);
+		if (!instance) return this._new(attrs, options);
+		instance.set(attrs);
+		Store.trigger("update", instance, this);
+		return instance;
+	},
+	find(id) {
+		const key = this._key(id);
+		if (key == null) return;
+		return this.instances[key];
+	},
+	has(id) {
+		return !!this.find(id);
+	},
+	patch(id, attrs, options) {
+		const instance = this.find(id);
+		if (!instance) return;
+		instance.set(attrs, options);
+		Store.trigger("update", instance, this);
+		return instance;
+	},
+	evict(id) {
+		return this._removeKey(this._key(id));
+	},
+	inspect(id) {
+		const key = this._key(id);
+		const model = key == null ? void 0 : this.instances[key];
+		return {
+			modelName: this.modelName,
+			id,
+			key,
+			cached: !!model,
+			model
+		};
+	},
+	reset() {
+		Object.keys(this.instances).forEach((key) => {
+			this._detachCached(this.instances[key]);
+		});
+		this.pending.slice().forEach((instance) => {
+			this._detachPending(instance);
+		});
+		this.instances = createCache();
+		this.pending = [];
+	},
+	_new(attrs, options) {
+		const instance = new this.Model(attrs, options);
+		if (instance.isNew()) this._trackPending(instance);
+		else this._add(instance);
+		return instance;
+	},
+	_add(instance) {
+		const key = this._getModelKey(instance);
+		this._detachPending(instance);
+		if (key == null) return;
+		if (this.instances[key]) return;
+		this.instances[key] = instance;
+		this._attachCached(instance);
+		Store.trigger("add", instance, this);
+	},
+	remove(instance) {
+		this._removeKey(this._getModelKey(instance), instance);
+		return instance;
+	},
+	_getKey(attrs) {
+		return attrs && this._key(attrs[this.Model.prototype.idAttribute]);
+	},
+	_getModelKey(instance) {
+		if (!instance) return;
+		return this._key(instance.id);
+	},
+	_key(id) {
+		if (id == null) return;
+		return String(id);
+	},
+	_trackPending(instance) {
+		this.pending.push(instance);
+		instance.once(`change:${instance.idAttribute}`, this._add, this);
+		instance.on("destroy", this._removePending, this);
+	},
+	_removePending(instance) {
+		this._detachPending(instance);
+	},
+	_detachPending(instance) {
+		const index = this.pending.indexOf(instance);
+		if (index > -1) this.pending.splice(index, 1);
+		instance.off(`change:${instance.idAttribute}`, this._add, this);
+		instance.off("destroy", this._removePending, this);
+	},
+	_attachCached(instance) {
+		instance.on("destroy", this.remove, this);
+	},
+	_detachCached(instance) {
+		instance.off("destroy", this.remove, this);
+	},
+	_removeKey(key, eventInstance) {
+		if (key == null) return;
+		const instance = this.instances[key];
+		if (!instance) return;
+		delete this.instances[key];
+		this._detachCached(instance);
+		Store.trigger("remove", eventInstance || instance, this);
+		return instance;
+	}
+});
+//#endregion
+//#region lib/index.js
+let ModelCaches = {};
+const STORE_INSPECT_LABEL = "[Backbone.Store]";
+const nodeInspectSymbol = typeof Symbol === "function" && Symbol.for && Symbol.for("nodejs.util.inspect.custom");
+function isCustomInspectCall(modelName, id) {
+	return typeof modelName === "number" && (id == null || typeof id === "object");
+}
+/**
+* Store wrapper converts regular Backbone models into unique ones.
+*
+* Example:
+*   const StoredUser = Store(User);
+*/
+function Store(Model, modelName = (0, underscore.uniqueId)("Store_")) {
+	return Store.add(Model, modelName).ModelConstructor;
+}
+(0, underscore.extend)(Store, backbone.default.Events, {
+	ModelCache,
+	add(Model, modelName) {
+		if (!modelName) throw "Model name required";
+		if (ModelCaches[modelName]) return ModelCaches[modelName];
+		return ModelCaches[modelName] = new Store.ModelCache(Model, modelName);
+	},
+	getCache(modelName) {
+		if (!ModelCaches[modelName]) throw `Unrecognized Model: "${modelName}"`;
+		return ModelCaches[modelName];
+	},
+	getAllCache() {
+		return (0, underscore.clone)(ModelCaches);
+	},
+	get(modelName) {
+		return Store.getCache(modelName).ModelConstructor;
+	},
+	find(modelName, id) {
+		return Store.getCache(modelName).find(id);
+	},
+	has(modelName, id) {
+		return Store.getCache(modelName).has(id);
+	},
+	patch(modelName, id, attrs, options) {
+		return Store.getCache(modelName).patch(id, attrs, options);
+	},
+	evict(modelName, id) {
+		return Store.getCache(modelName).evict(id);
+	},
+	inspect(modelName, id) {
+		if (isCustomInspectCall(modelName, id)) return STORE_INSPECT_LABEL;
+		return Store.getCache(modelName).inspect(id);
+	},
+	getAll() {
+		return (0, underscore.reduce)(ModelCaches, (all, cache, modelName) => {
+			all[modelName] = cache.ModelConstructor;
+			return all;
+		}, {});
+	},
+	reset(modelName) {
+		Store.getCache(modelName).reset();
+	},
+	resetAll() {
+		(0, underscore.each)(ModelCaches, (cache) => {
+			cache.reset();
+		});
+	},
+	remove(modelName) {
+		if (!ModelCaches[modelName]) return;
+		ModelCaches[modelName].reset();
+		delete ModelCaches[modelName];
+	},
+	removeAll() {
+		Store.resetAll();
+		ModelCaches = {};
+	}
+});
+if (nodeInspectSymbol) Store[nodeInspectSymbol] = () => STORE_INSPECT_LABEL;
+backbone.default.Store = Store;
+//#endregion
+exports.ModelCache = ModelCache;
+exports.default = Store;
+
+//# sourceMappingURL=backbone.store.cjs.map