seqda 1.1.3 → 2.1.0

package/.eslintrc.cjs

@@ -0,0 +1,95 @@
+'use strict';
+
+/* eslint-disable no-magic-numbers */
+
+module.exports = {
+  'env': {
+    'browser':  true,
+    'commonjs': true,
+    'es2021':   true,
+  },
+  'extends': [
+    'eslint:recommended',
+  ],
+  'parserOptions': {
+    'ecmaVersion':  'latest',
+    'sourceType':   'module',
+  },
+  'plugins': [
+    '@spothero/eslint-plugin-spothero',
+  ],
+  'rules': {
+    '@spothero/spothero/ternary-parentheses': 'error',
+    'arrow-parens':                           'error',
+    'arrow-spacing':                          [ 'error', { before: true, after: true } ],
+    'block-scoped-var':                       'warn',
+    'block-spacing':                          'error',
+    'brace-style':                            [ 'error', '1tbs' ],
+    'camelcase':                              'warn',
+    'comma-dangle':                           [ 'error', 'always-multiline' ],
+    'comma-spacing':                          [ 'error', { before: false, after: true } ],
+    'comma-style':                            [ 'error', 'last' ],
+    'curly':                                  [ 'error', 'multi-or-nest', 'consistent' ],
+    'default-case-last':                      'error',
+    'default-param-last':                     'error',
+    'eqeqeq':                                 [ 'error', 'smart' ],
+    'func-call-spacing':                      [ 'error', 'never' ],
+    'guard-for-in':                           'error',
+    'implicit-arrow-linebreak':               [ 'error', 'beside' ],
+    'indent':                                 [ 'error', 2, { 'SwitchCase': 1 } ],
+    'jsx-quotes':                             [ 'error', 'prefer-double' ],
+    'key-spacing':                            [ 'error', { beforeColon: false, afterColon: true, mode: 'minimum', 'align': 'value' } ],
+    'keyword-spacing':                        [ 'error', { before: true, after: true } ],
+    'linebreak-style':                        [ 'error', 'unix' ],
+    'lines-between-class-members':            'error',
+    'max-classes-per-file':                   [ 'error', 3 ],
+    'new-cap':                                [ 'error', { 'properties': false } ],
+    'new-parens':                             'error',
+    'no-array-constructor':                   'warn',
+    'no-caller':                              'error',
+    'no-confusing-arrow':                     'error',
+    'no-empty':                               'warn',
+    'no-eq-null':                             0,
+    'no-eval':                                'error',
+    'no-extend-native':                       'error',
+    'no-extra-label':                         'error',
+    'no-floating-decimal':                    'error',
+    'no-global-assign':                       'error',
+    'no-implied-eval':                        'error',
+    'no-labels':                              'error',
+    'no-lone-blocks':                         'warn',
+    'no-loop-func':                           0,
+    'no-magic-numbers':                       [ 'warn', { ignoreArrayIndexes: true, ignoreDefaultValues: true, ignore: [ -1, 0, 1, 2, 16, 32, 64, 128, 256, 1024, 2048, 200, 301, 302, 400, 401, 404, 500 ] } ],
+    'no-nested-ternary':                      'error',
+    'no-param-reassign':                      'error',
+    'no-promise-executor-return':             'error',
+    'no-return-assign':                       'error',
+    'no-sequences':                           'error',
+    'no-shadow':                              0,
+    'no-throw-literal':                       'warn',
+    'no-trailing-spaces':                     'error',
+    'no-unmodified-loop-condition':           'warn',
+    'no-unreachable-loop':                    'warn',
+    'no-unreachable':                         'warn',
+    'no-unused-private-class-members':        'warn',
+    'no-unused-vars':                         'warn',
+    'no-whitespace-before-property':          'error',
+    'nonblock-statement-body-position':       [ 'error', 'below' ],
+    'one-var':                                [ 'error', 'never' ],
+    'quotes':                                 [ 'error', 'single' ],
+    'radix':                                  'error',
+    'rest-spread-spacing':                    [ 'error', 'never' ],
+    'semi-spacing':                           [ 'error', { before: false, after: true } ],
+    'semi-style':                             [ 'error', 'last' ],
+    'semi':                                   'error',
+    'space-before-blocks':                    'error',
+    'space-infix-ops':                        'error',
+    'space-unary-ops':                        [ 'error', { words: false, nonwords: false } ],
+    'strict':                                 'error',
+    'switch-colon-spacing':                   [ 'error', { before: false, after: true } ],
+    'template-curly-spacing':                 'error',
+    'template-tag-spacing':                   'error',
+    'wrap-iife':                              [ 'error', 'inside' ],
+    'yoda':                                   'error',
+  },
+};

package/README.md

@@ -23,7 +23,8 @@ There are no actions, dispatches, reducers, or selectors per-se. Instead, there
 In `seqda` there are a few key principles that will be mentioned throughout this document. Let's create a simple store to explain these principles and terminology:
 
 ```javascript
-const { createStore } = require('seqda');
+import { createStore } from 'seqda';
+
 const MyStore = createStore({
   todos: { // This is a "scope"
     _: [], // This is the "default value" for this scope
@@ -84,52 +85,77 @@ const MyStore = createStore({
 
     // Methods go here
   }
-})
+});
 
 // We can add a todo by calling our method
-// (notice that the "context") argments ({ get, set })
-// are provided internally by seqda
+// (notice that the "context" arguments ({ get, set })
+// are provided internally by seqda)
 
-MyStore.todos.add(/* todo */ { todo: 'Do things!', id: 1 });
+MyStore.todos.add({ todo: 'Do things!', id: 1 });
 
 console.log(MyStore.getState());
-
-{
-  "todos": [
-    { "todo": "Do things!", "id": 1 },
-  ],
-  "config": {
-    "configValue1": null,
-    "configValue2": null,
-    'userConfig": {
-      "firstName": '',
-      "lastName": '',
-    }
-  }
-}
+// {
+//   "todos": [
+//     { "todo": "Do things!", "id": 1 }
+//   ],
+//   "config": {
+//     "configValue1": null,
+//     "configValue2": null,
+//     "userConfig": {
+//       "firstName": "",
+//       "lastName": ""
+//     }
+//   }
+// }
 ```
 
-## The entire store is frozen
+## Immutability
 
-In `seqda`, all values in the store are always frozen with `Object.freeze`. This ensures that your store stays immutable, and can only be updated with the provided scope methods. For example, if you try to set something directly on the returned state, it will fail:
+In `seqda`, the store's internal state tree is frozen with `Object.freeze`. This ensures structural immutability — the state can only be updated through scope methods via `set()`.
 
 ```javascript
 let state = MyStore.getState();
 state.setSomething = toAValue;
+// TypeError: Cannot add property setSomething, object is not extensible
+```
+
+**Important:** The freeze is *shallow* — it applies to the state tree nodes (objects and arrays at each path level) but does **not** deep-freeze objects stored as values inside those containers. For example, if you store an object inside an array scope, the array is frozen (you can't push/pop), but the object itself remains mutable:
 
-// throw new TypeError('Cannot add property setSomething, object is not extensible');
+```javascript
+import { createStore } from 'seqda';
+
+const store = createStore({
+  items: {
+    _: [],
+    add({ get, set }, item) {
+      set([...get(), item]);
+    },
+    get({ get }) {
+      return get();
+    },
+  },
+});
+
+let item = { name: 'test', mutable: true };
+store.items.add(item);
+
+let items = store.items.get();
+items.push('fail');              // TypeError — array is frozen
+items[0].name = 'modified';     // Works — item object is NOT frozen
 ```
 
+This is by design. It keeps seqda lightweight and allows consumers to manage their own object immutability strategy (e.g., `Object.freeze` at the application level, or treating objects as immutable by convention).
+
 ## Method cache
 
 All scope methods in `seqda` are cached by default. For this reason, it is fine to have getters that contain complex logic and filtering.
 
-The cache is invalidated as soon as 1) the internal state for a scope is updated, or 2) the arguments to the method call change.
+The cache is invalidated as soon as 1) the internal state for a scope is updated via `set()`, or 2) the arguments to the method call change.
 
 Let's see an example of this in action:
 
 ```javascript
-const { createStore } = require('seqda');
+import { createStore } from 'seqda';
 
 const MyStore = createStore({
   citizens: {
@@ -142,18 +168,14 @@ const MyStore = createStore({
     _: [],
     get({ get }, stateName) {
       if (!stateName)
-        return get(); // if no stateName was provided, then return all states
+        return get();
 
       return get().find((state) => (state.name === stateName));
     },
     getCitizensForState({ get, store }, stateName) {
-      // First, get the state requested from the store
       let state = store.states.get(stateName);
-
-      // Next get the citizens for this state
-      // This is now cached, so as long as the
-      // arguments (shortStateName) remain the
-      // same, we can quickly call this over and over.
+      // Cached — as long as shortStateName stays the same,
+      // repeated calls return instantly.
       let citizens = store.citizens.getByState(state.shortName);
       return citizens;
     }
@@ -163,50 +185,102 @@ const MyStore = createStore({
 
 ## Update events
 
-`seqda` emits an `'update'` event when the store has been updated. Unlike Redux, the `'update'` event is only triggered on the *next frame* in the Javascript engine (essentially on `nextTick`). The update event also reports which areas of the store have been updated, unlike Redux. This allows many store updates to happen sequentially, with the update event only being fired once. Let's see an example of this in action.
+`seqda` emits an `'update'` event when the store has been updated. Unlike Redux, the `'update'` event is only triggered on the *next microtask* (via `Promise.resolve().then(...)`). The update event reports which scopes were modified, and provides a frozen read-only snapshot of the previous state. This allows many store updates to happen sequentially, with only one event fired.
 
-*Note: When the scope name of the update event is `'*'`, this means that the entire store has been updated. This can happen for example when the store is hydrated with a `.hydrate` call.*
+*Note: When the scope name in the `modified` array is `'*'`, the entire store has been updated (e.g., via `.hydrate()`).*
 
 ```javascript
-const { createStore } = require('seqda');
+import { createStore } from 'seqda';
+
 const MyStore = createStore({
   todos: {
     _: [],
     add({ get, set }, todo) {
       set([ ...get(), todo ]);
     },
-    remove({ get, set }, todo) {
-      set(get().filter((item) => (item !== todo)));
-    },
-    get({ get }, todoID) {
-      if (arguments.length === 1)
-        return get();
-
-      return get().find((todo) => (todo.id === todoID));
+    get({ get }) {
+      return get();
     },
   },
 });
 
-MyStore.on('update', ({ store, modified }) => {
-  // I am called on `nextTick`, frame 2
-  console.log('modified: ', modified);
+MyStore.on('update', ({ store, previousStore, modified }) => {
+  console.log('modified scopes:', modified);
+  // modified scopes: [ 'todos' ]
 
-  // modified: [ 'todos' ]
+  // previousStore is a frozen read-only clone of the state
+  // before this batch of updates:
+  console.log('before:', previousStore.todos.get());
+  console.log('after:', store.todos.get());
 });
 
-// frame 1
+// Both adds happen in the same synchronous block —
+// only ONE update event fires, listing 'todos' once.
 MyStore.todos.add({ todo: 'Do something!', id: 1 });
 MyStore.todos.add({ todo: 'Do another thing!', id: 2 });
+```
+
+### Sub-scope paths in `modified`
+
+When a sub-scope is updated, the `modified` array contains the dot-separated path to that specific sub-scope:
+
+```javascript
+import { createStore } from 'seqda';
+
+const store = createStore({
+  data: {
+    _: [],
+    config: {
+      _: { theme: 'dark' },
+      set({ get, set }, values) {
+        set({ ...get(), ...values });
+      },
+    },
+  },
+});
+
+store.on('update', ({ modified }) => {
+  console.log(modified);
+  // [ 'data.config' ]  — the specific sub-scope path
+});
 
-//... now onto frame2, where the "update" event is fired
+store.data.config.set({ theme: 'light' });
+```
+
+### Custom events
+
+The seqda store IS a Node.js `EventEmitter`. You can emit your own custom events through it alongside seqda's built-in events. Custom events fire **synchronously** (unlike seqda's batched `update` event):
+
+```javascript
+import { createStore } from 'seqda';
+
+const store = createStore({
+  items: {
+    _: {},
+    put({ get, set }, item) {
+      set({ ...get(), [item.id]: item });
+    },
+  },
+});
+
+// Subscribe to a custom namespaced event
+store.on('item:added:abc123', (data) => {
+  console.log('Item added:', data.item);
+});
+
+// Your wrapper can emit custom events synchronously
+// during operations, while seqda handles state batching:
+let item = { id: 'abc123', name: 'test' };
+store.items.put(item);
+store.emit(`item:added:${item.id}`, { item });
 ```
 
 ## Fetch events
 
-`seqda` also reports which scopes are being fetched. Simply listen for the "fetchScope" event to know which areas of the store have been accessed for any given operation.
+`seqda` can report which scopes are being read. Enable with `{ emitOnFetch: true }` and listen for the `'fetchScope'` event:
 
 ```javascript
-const { createStore } = require('seqda');
+import { createStore } from 'seqda';
 
 const MyStore = createStore({
   todos: {
@@ -214,29 +288,20 @@ const MyStore = createStore({
     add({ get, set }, todo) {
       set([ ...get(), todo ]);
     },
-    remove({ get, set }, todo) {
-      set(get().filter((item) => (item !== todo)));
-    },
-    get({ get }, todoID) {
-      if (arguments.length === 1)
-        return get();
-
-      return get().find((todo) => (todo.id === todoID));
+    get({ get }) {
+      return get();
     },
   },
-});
+}, { emitOnFetch: true });
 
 MyStore.todos.add({ todo: 'Do something!', id: 1 });
-MyStore.todos.add({ todo: 'Do another thing!', id: 2 });
 
 MyStore.on('fetchScope', ({ store, scopeName }) => {
-  console.log('scope fetched: ', scopeName);
+  console.log('scope fetched:', scopeName);
 });
 
 MyStore.todos.get();
-
-// output:
-// scoped fetched: todos
+// output: scope fetched: todos
 ```
 
 ## Async methods
@@ -244,7 +309,7 @@ MyStore.todos.get();
 There is nothing in `seqda` preventing you from using async methods. The store will only update once `set` is called inside a method, and `set` won't be called until your asynchronous code is complete.
 
 ```javascript
-const { createStore } = require('seqda');
+import { createStore } from 'seqda';
 
 const MyStore = createStore({
   users: {
@@ -263,41 +328,117 @@ const MyStore = createStore({
   },
 });
 
-let user = await MyStore.getUser(1);
+let user = await MyStore.users.getUser(1);
 ```
 
-Keep in mind that methods inside `seqda` are not asynchronous in nature, so the result of the above `getUser` call will cache the returned promise (not the resolved value of that promise). Now this shouldn't be an issue, because if you have an asynchronous method, so you will always be awaiting on the result, so the cached promise--if returned from cache--will provide the same result.
+Keep in mind that methods inside `seqda` are not asynchronous in nature, so the result of the above `getUser` call will cache the returned promise (not the resolved value of that promise). Now this shouldn't be an issue, because if you have an asynchronous method, you will always be awaiting on the result, so the cached promise--if returned from cache--will provide the same result.
 
 ```javascript
 // Caches the promise
-let user = await MyStore.getUser(1);
+let user = await MyStore.users.getUser(1);
 
 // Returns the cached promise
-user = await MyStore.getUser(1);
+user = await MyStore.users.getUser(1);
 
 // Result = same
 ```
 
-## Seqda is built for speed an simplicity
+## Performance
+
+Unlike Redux, where dispatching an action recalculates the entire store, `seqda` only updates the specific scope (and its parent path) that was modified. Combined with per-method caching and batched update events, this makes `seqda` efficient for high-frequency updates.
+
+The `'update'` event fires once per microtask tick after all synchronous writes settle. If you have UI components listening for store updates, they re-render once after the batch — not once per write.
+
+## Cloning stores
+
+You can clone a store with `cloneStore()`. Cloned stores are fully independent — mutations in the clone don't affect the original.
+
+```javascript
+import { createStore, cloneStore } from 'seqda';
+
+const store = createStore({
+  todos: {
+    _: [],
+    add({ get, set }, todo) {
+      set([...get(), todo]);
+    },
+    get({ get }) {
+      return get();
+    },
+  },
+});
+
+store.todos.add({ id: 1, text: 'Original' });
+
+// Mutable clone
+let clone = cloneStore(store);
+clone.todos.add({ id: 2, text: 'Clone only' });
+
+console.log(store.todos.get().length);  // 1
+console.log(clone.todos.get().length);  // 2
+
+// Read-only clone (set() calls are silently ignored)
+let snapshot = cloneStore(store, true);
+snapshot.todos.add({ id: 3, text: 'Ignored' });
+console.log(snapshot.todos.get().length);  // 1
+```
+
+## Hydrating the store
+
+To restore a store from a saved state, use `hydrate()`. This replaces the entire internal state atomically and emits an update with `modified: ['*']`.
 
-Unlike in Redux, where when an action is dispatched, the entire store is recalculated (which can be very heavy for large stores), `seqda` will only update the specific area of the store (and all its parent scopes) that was requested to be updated. This means that for each update operation, only the updated scope (and all parent) scopes are updated, making it much more efficient than Redux.
+```javascript
+let savedState = JSON.stringify(MyStore.getState());
 
-Also, as already mentioned, the `seqda` `'update'` event is only fired once after all the store updates have settled (on `nextTick` after updates). This is also for efficiency purposes. For example, if you have client components (i.e. React) listening for store updates, then unlike Redux, where the component's state will potentially update dozens of times for a single store dispatch, in `seqda` all your components will only update their state once after the store has settled.
+// Later...
+MyStore.hydrate(JSON.parse(savedState));
+```
 
-The `seqda` interface was designed to be simple and intuitive. All you really need to understand is scopes, and how to interact with them via `get`, `set`, and fetching other values from the store via `store`. The rest is up to you! Feel free to create complicated caching selectors, or any other useful tools you want. You just need to provide methods to interact with your scopes, and the rest is left to your creative freedom!
+`hydrate()` also invalidates all scope method caches, so any subsequent calls to cached methods will re-read from the new state.
 
 ## Middleware
 
 Middleware is not currently supported, but I would be happy to add it (or to accept a PR) if anyone needs middleware.
 
-## Hydrating the store from a stored state
+## API Reference
 
-To hydrate your store from a stored state, simply call `MyStore.hydrate(storedState)`.
+### `createStore(template, options?)`
 
-```javascript
+Creates a new seqda store.
 
-let storedState = JSON.stringify(MyStore.getState());
+- **`template`** — Object defining scopes. Each scope has a `_` default value and named methods.
+- **`options.emitOnFetch`** — `boolean` (default: `false`). When `true`, emits `'fetchScope'` events on scope reads.
 
-MyStore.hydrate(JSON.parse(storedState));
+Returns the store instance (an `EventEmitter` with scope methods attached).
 
-```
+### Store instance
+
+| Method/Property | Description |
+|---|---|
+| `store.getState()` | Returns the current frozen internal state object |
+| `store.hydrate(state)` | Replaces entire state, emits update with `modified: ['*']` |
+| `store.on(event, listener)` | Subscribe to events (inherited from EventEmitter) |
+| `store.off(event, listener)` | Unsubscribe from events |
+| `store.emit(event, data)` | Emit custom events |
+
+### Scope method context
+
+Every scope method receives a context object as its first argument:
+
+| Property | Description |
+|---|---|
+| `get()` | Read the current state for this scope |
+| `set(value)` | Write a new value for this scope (must be a different reference) |
+| `store` | Reference to the root store — access other scopes |
+
+### Events
+
+| Event | Payload | Timing |
+|---|---|---|
+| `'update'` | `{ store, previousStore, modified }` | Async (next microtask), batched |
+| `'fetchScope'` | `{ store, scopeName }` | Sync (immediate), opt-in |
+| Custom events | User-defined | Sync (immediate) |
+
+### `cloneStore(store, readOnly?)`
+
+Creates a deep clone of the store. If `readOnly` is `true`, all `set()` calls are silently ignored.