^ Subscriptions are now tracked by field

This means subscriptions will not fire if the thing they are tracking
hasn't changed.

This has also had an affect on when state officially changes which is
now only after an emit.

Author: will-stone

README.md

@@ -358,6 +358,10 @@ class Store extends TwoAndEight {
 export const useStore = createReactStore(new Store())
 ```
 
+> [!NOTE]  
+> `$` prefixed actions are not available to select from `useStore`, this is
+> because these should be called from other public actions.
+
 ## Comparison
 
 2n8 feels like a blend between two excellent state management libraries:
@@ -690,32 +694,18 @@ available.
 #### `useStore.subscribe`
 
 ```ts
-useStore.subscribe(callback: () => void): () => void
+useStore.subscribe(field: Field, callback: () => void): () => void
 ```
 
-Subscribes to state updates; registers a callback that fires whenever an action
-emits. This can be used to trigger events when all or certain state changes.
+Subscribes to state updates for a particular field or getter; registers a
+callback that fires whenever an action emits that affects the chosen field.
 
 ```ts
-useStore.subscribe(() => {
+useStore.subscribe('counter', () => {
   writeCounterToFile(useStore.get('counter'))
 })
 ```
 
-Note that this will be called on every emitted state from the store. If you'd
-like to optimise, it is advisable to use `if` statements and an external cache:
-
-```ts
-let counterCache = useStore.get('counter')
-
-useStore.subscribe(() => {
-  if (useStore.get('counter') !== counterCache) {
-    writeCounterToFile(useStore.get('counter'))
-    counterCache = useStore.get('counter')
-  }
-})
-```
-
 ### `createStore`
 
 ```ts
@@ -737,16 +727,8 @@ available.
 #### `store.subscribe`
 
 ```ts
-store.subscribe(callback: () => void): () => void
+store.subscribe(field: Field, callback: () => void): () => void
 ```
 
 Subscribes to state updates; registers a callback that fires whenever an action
-emits. This can be used to trigger events when all or certain state changes.
-
-#### `store.getInitialState`
-
-```ts
-store.getInitialState(): Store
-```
-
-Returns the initial state snapshot, before any mutations have occurred.
+emits and the selected field is changed.

src/2n8.bench.ts

@@ -23,7 +23,7 @@ describe('simple count', () => {
 
   bench('2n8', async () => {
     const subscriptionComplete = new Promise<void>((resolve) => {
-      twoAndEightSubscribe(() => {
+      twoAndEightSubscribe('count', () => {
         if (get('count') === 1) {
           resolve()
         }

src/2n8.test.tsx

@@ -52,7 +52,7 @@ test('should update when using async actions', async () => {
   expect(get('count')).toBe(7)
 })
 
-test('should always return master record', async () => {
+test('should only return updated state after emit', async () => {
   class Store extends TwoAndEight {
     count = 0
 
@@ -67,6 +67,15 @@ test('should always return master record', async () => {
       })
       this.count = this.count + 5
     }
+
+    asyncWithEarlyEmitButtonClicked = async () => {
+      this.count++
+      this.$emit()
+      await new Promise((res) => {
+        setTimeout(res, 1000)
+      })
+      this.count = this.count + 2
+    }
   }
 
   const { get } = createStore(new Store())
@@ -75,7 +84,7 @@ test('should always return master record', async () => {
 
   get('asyncButtonClicked')()
 
-  expect(get('count')).toBe(1)
+  expect(get('count')).toBe(0)
 
   get('buttonClicked')()
 
@@ -84,6 +93,14 @@ test('should always return master record', async () => {
   await vi.advanceTimersByTimeAsync(3000)
 
   expect(get('count')).toBe(7)
+
+  get('asyncWithEarlyEmitButtonClicked')()
+
+  expect(get('count')).toBe(8)
+
+  await vi.advanceTimersByTimeAsync(1000)
+
+  expect(get('count')).toBe(10)
 })
 
 test('should reset all state', () => {
@@ -467,8 +484,6 @@ test('should return current state', () => {
   const { get, subscribe } = createStore(new Store())
   get('increaseCount')()
 
-  expect(get('$emit')).toStrictEqual(expect.any(Function))
-  expect(get('$reset')).toStrictEqual(expect.any(Function))
   expect(get('increaseCount')).toStrictEqual(expect.any(Function))
   expect(get('count')).toBe(1)
   expect(get('untouched')).toBe('foo')
@@ -496,14 +511,18 @@ test('should not call subscriber when state has not changed', () => {
 
   const { get, subscribe } = createStore(new Store())
   const subscribeSpy = vi.fn<() => void>()
-  subscribe(subscribeSpy)
+  const subscribe2Spy = vi.fn<() => void>()
+  subscribe('count', subscribeSpy)
+  subscribe('obj', subscribe2Spy)
   get('noop')()
 
-  expect(subscribeSpy).toHaveBeenCalledOnce()
+  expect(subscribeSpy).not.toHaveBeenCalled()
+  expect(subscribe2Spy).not.toHaveBeenCalled()
 
   get('noop2')()
 
-  expect(subscribeSpy).toHaveBeenCalledTimes(2)
+  expect(subscribeSpy).not.toHaveBeenCalled()
+  expect(subscribe2Spy).not.toHaveBeenCalled()
 })
 
 test('should unsubscribe', () => {
@@ -517,7 +536,7 @@ test('should unsubscribe', () => {
 
   const { get, subscribe } = createStore(new Store())
   const spy = vi.fn<() => void>()
-  const unsubscribe = subscribe(spy)
+  const unsubscribe = subscribe('count', spy)
   get('increaseCount')()
 
   expect(spy).toHaveBeenCalledOnce()
@@ -576,8 +595,9 @@ test('should update deep state', () => {
   }
 
   const { get, subscribe } = createStore(new Store())
-  const subscribeSpy = vi.fn<() => void>()
-  subscribe(subscribeSpy)
+  // TODO test other fields
+  const objSubscribeSpy = vi.fn<() => void>()
+  subscribe('obj', objSubscribeSpy)
 
   expect(get('obj')).toStrictEqual({ foo: { bar: 'baz' } })
   expect(get('arr')).toStrictEqual(['hello'])
@@ -587,13 +607,13 @@ test('should update deep state', () => {
   get('other')()
   get('push')()
 
-  expect(subscribeSpy).toHaveBeenCalledTimes(4)
+  expect(objSubscribeSpy).toHaveBeenCalledOnce()
   expect(get('obj')).toStrictEqual({ foo: { bar: 'moo' } })
   expect(get('arr')).toStrictEqual(['hello', 'bye'])
 
   get('delete')()
 
-  expect(subscribeSpy).toHaveBeenCalledTimes(5)
+  expect(objSubscribeSpy).toHaveBeenCalledTimes(2)
   expect(get('obj')).toStrictEqual({ foo: {} })
   expect(get('arr')).toStrictEqual(['hello', 'bye'])
 })
@@ -616,7 +636,7 @@ test('should not fire subscription until end of action', () => {
 
   const { get, subscribe } = createStore(new Store())
   const subscribeSpy = vi.fn<() => void>()
-  subscribe(subscribeSpy)
+  subscribe('count', subscribeSpy)
   get('increment')()
 
   expect(subscribeSpy).toHaveBeenCalledOnce()
@@ -627,22 +647,32 @@ test('should not fire subscription until end of action', () => {
   expect(subscribeSpy).toHaveBeenCalledTimes(2)
 })
 
-test('should not fire subscription if action begins with $ but state still updates', () => {
+test('should not fire subscription if action begins with $ and not update state until emit-able action called', () => {
   class Store extends TwoAndEight {
     count = 999
 
     $increment = () => {
       this.count++
     }
+
+    increment = () => {
+      this.count++
+    }
   }
 
   const { get, subscribe } = createStore(new Store())
   const subscribeSpy = vi.fn<() => void>()
-  subscribe(subscribeSpy)
+  subscribe('count', subscribeSpy)
+  // @ts-expect-error -- normally you shouldn't call $ actions directly.
   get('$increment')()
 
-  expect(get('count')).toBe(1000)
+  expect(get('count')).toBe(999)
   expect(subscribeSpy).not.toHaveBeenCalled()
+
+  get('increment')()
+
+  expect(get('count')).toBe(1001)
+  expect(subscribeSpy).toHaveBeenCalledOnce()
 })
 
 test("should fail types when store hasn't extended super class", () => {

src/2n8.ts

@@ -16,11 +16,15 @@ function infuseWithCallbackAfterRun(
   }
 }
 
-export type State<Store> = {
+export type StateFields<Store> = {
   // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
   [K in keyof Store as Store[K] extends Function ? never : K]: Store[K]
 }
 
+export type StateFieldsAndPublicActions<Store> = {
+  [K in keyof Store]: K extends `$${string}` ? never : K
+}[keyof Store]
+
 export abstract class TwoAndEight {
   $emit(): void {
     // no-op, for now, it's enhanced in createStore
@@ -40,14 +44,47 @@ export abstract class TwoAndEight {
 export function createStore<Store extends TwoAndEight>(
   store: Store,
 ): {
-  get: <Field extends keyof Store>(field: Field) => Store[Field]
-  subscribe: (subscriber: () => void) => () => void
+  get: <Field extends StateFieldsAndPublicActions<Store>>(
+    field: Field,
+  ) => Store[Field]
+  subscribe: <Field extends keyof StateFields<Store>>(
+    field: Field,
+    subscriber: () => void,
+  ) => () => void
 } {
-  const subscribers = new Set<() => void>()
+  const storeCache = {} as StateFields<Store>
+
+  const proto = Object.getPrototypeOf(store)
+
+  const getterNames = Object.getOwnPropertyNames(proto).filter((name) => {
+    const descriptor = Object.getOwnPropertyDescriptor(proto, name)
+    return descriptor && typeof descriptor.get === 'function'
+  })
+
+  const stateNames = (
+    Object.keys(store) as (keyof StateFields<Store>)[]
+  ).filter((key) => typeof store[key] !== 'function')
+
+  const fields = [...getterNames, ...stateNames] as (keyof StateFields<Store>)[]
+
+  for (const field of fields) {
+    storeCache[field] = structuredClone(store[field])
+  }
+
+  const subscribers = {} as Record<keyof StateFields<Store>, Set<() => void>>
+
+  for (const field of fields) {
+    subscribers[field] = new Set<() => void>()
+  }
 
   store.$emit = () => {
-    for (const subscriber of subscribers) {
-      subscriber()
+    for (const field of fields) {
+      if (!isEqual(store[field], storeCache[field])) {
+        storeCache[field] = structuredClone(store[field])
+        for (const subscriber of subscribers[field]) {
+          subscriber()
+        }
+      }
     }
   }
 
@@ -70,7 +107,7 @@ export function createStore<Store extends TwoAndEight>(
     }
   }
 
-  store.$reset = (field?: keyof State<Store>): void => {
+  store.$reset = (field?: keyof StateFields<Store>): void => {
     if (field) {
       const value = Reflect.get(store, field)
       if (typeof value === 'function') {
@@ -90,23 +127,21 @@ export function createStore<Store extends TwoAndEight>(
     }
   }
 
-  const subscribe = (subscriber: () => void): (() => void) => {
-    subscribers.add(subscriber)
-    return () => subscribers.delete(subscriber)
+  const subscribe = <Field extends keyof StateFields<Store>>(
+    field: Field,
+    subscriber: () => void,
+  ): (() => void) => {
+    subscribers[field].add(subscriber)
+    return () => subscribers[field].delete(subscriber)
   }
 
-  const cache = {} as Store
-
   const get = <Field extends keyof Store>(field: Field) => {
     if (typeof store[field] === 'function') {
       return store[field]
     }
 
-    if (!isEqual(store[field], cache[field])) {
-      cache[field] = structuredClone(store[field])
-    }
-
-    return cache[field]
+    // Pretending to be store because we've already removed actions above.
+    return (storeCache as Store)[field]
   }
 
   return {

src/react.tsx

@@ -1,23 +1,39 @@
 import { useSyncExternalStore } from 'react'
 
-import type { TwoAndEight } from './2n8.js'
+import type {
+  StateFieldsAndPublicActions,
+  StateFields,
+  TwoAndEight,
+} from './2n8.js'
 import { createStore } from './2n8.js'
 
 export function createReactStore<Store extends TwoAndEight>(
   rawStore: Store,
-): (<Field extends keyof Omit<Store, '$emit' | '$reset'>>(
+): (<Field extends StateFieldsAndPublicActions<Store>>(
   field: Field,
 ) => Store[Field]) & {
-  get: <Field extends keyof Omit<Store, '$emit' | '$reset'>>(
+  get: <Field extends StateFieldsAndPublicActions<Store>>(
     field: Field,
   ) => Store[Field]
-  subscribe: (subscriber: () => void) => () => void
+  subscribe: <Field extends keyof StateFields<Store>>(
+    field: Field,
+    subscriber: () => void,
+  ) => () => void
 } {
   const { get, subscribe } = createStore(rawStore)
 
-  function useStore<Field extends keyof Store>(field: Field): Store[Field] {
+  function useStore<Field extends StateFieldsAndPublicActions<Store>>(
+    field: Field,
+  ): Store[Field] {
     return useSyncExternalStore(
-      subscribe,
+      (cb) =>
+        typeof rawStore[field] === 'function'
+          ? () => null
+          : subscribe(
+              // @ts-expect-error -- cannot subscribe to actions.
+              field,
+              cb,
+            ),
       () => get(field),
       () => get(field),
     )