Merge pull request #22 from nanostores/feat/actions-api

feat: actions api

Author: euaaaio

.github/workflows/test.yml

@@ -7,6 +7,9 @@ on:
       - next
   pull_request:
 
+permissions:
+  contents: read
+
 jobs:
   full:
     name: Node.js Latest Full

README.md

@@ -3,7 +3,7 @@
 <img align="right" width="92" height="92" title="Nano Stores logo"
      src="https://nanostores.github.io/nanostores/logo.svg">
 
-Logger of lifecycles and changes for **[Nano Stores]**,
+Logger of lifecycles, changes and actions for **[Nano Stores]**,
 a tiny state manager with many atomic tree-shakable stores.
 
 * **Clean.** All messages are stacked in compact, collapsible nested groups.
@@ -46,7 +46,7 @@ let destroy = logger({
 #### Disable specific types of logs
 
 Using `messages` option you can disable
-**mount**, **unmount** or **change** log messages.
+**mount**, **unmount**, **change** or **action** log messages.
 
 ```js
 import { logger } from '@nanostores/logger'
@@ -61,12 +61,30 @@ let destroy = logger({ $users }, {
 })
 ```
 
+#### Disable logs of actions with a specific name
+
+Using the `ignoreActions` option, you can specify the names of actions
+that will not be logged.
+
+```js
+import { logger } from '@nanostores/logger'
+
+import { $users } from './stores/index.js'
+
+let destroy = logger({ $users }, {
+  ignoreActions: [
+    'Change Username',
+    'Fetch User Profile'
+  ]
+})
+```
+
 ### Custom messages
 
 You can create custom log messages and collapsible nested groups of messages
 with your own name and badge color or with any predefined types.
 
-Available types: `arguments`, `build`, `change`, `error`, `mount`,
+Available types: `action`, `arguments`, `build`, `change`, `error`, `mount`,
 `new`, `old`, `unmount`, `value`.
 
 ```js
@@ -121,12 +139,29 @@ let destroy = buildLogger($profile, 'Profile', {
     console.log(`${storeName} was unmounted`)
   },
 
-  change: ({ storeName, changed, newValue, oldValue, valueMessage }) => {
+  change: ({ storeName, actionName, changed, newValue, oldValue, valueMessage }) => {
     let message = `${storeName} was changed`
     if (changed) message += `in the ${changed} key`
     if (oldValue) message += `from ${oldValue}`
     message += `to ${newValue}`
+    if (actionName) message += `by action ${actionName}`
     console.log(message, valueMessage)
+  },
+
+  action: {
+    start: ({ actionName, args }) => {
+      let message = `${actionName} was started`
+      if (args.length) message += 'with arguments'
+      console.log(message, args)
+    },
+
+    error: ({ actionName, error }) => {
+      console.log(`${actionName} was failed`, error)
+    },
+
+    end: ({ actionName }) => {
+      console.log(`${actionName} was ended`)
+    }
   }
 })
 ```

action/index.d.ts

@@ -0,0 +1,35 @@
+import type { WritableStore } from '../map/index.js'
+
+type OmitFirstArg<F> = F extends (x: any, ...args: infer P) => infer R
+  ? (...args: P) => R
+  : never
+
+export const lastActionName: unique symbol
+export const lastActionId: unique symbol
+
+/**
+ * Action is a function which changes the store.
+ *
+ * This wrap allows DevTools to see the name of action, which changes the store.
+ *
+ * ```js
+ * export const increase = action($counter, 'increase', ($store, value = 1) => {
+ *   if (validateMax($store.get() + value)) {
+ *     $store.set($store.get() + value)
+ *   }
+ *   return $store.get()
+ * })
+ *
+ * increase()  //=> 1
+ * increase(5) //=> 6
+ * ```
+ *
+ * @param store Store instance.
+ * @param actionName Action name for logs.
+ * @param cb Function changing the store.
+ * @returns Wrapped function with the same arguments.
+ */
+export function action<
+  SomeStore extends WritableStore,
+  Callback extends ($store: SomeStore, ...args: any[]) => any
+>(store: SomeStore, actionName: string, cb: Callback): OmitFirstArg<Callback>

action/index.js

@@ -0,0 +1,85 @@
+import { startTask } from 'nanostores'
+
+export let lastActionId = Symbol('last-action-id')
+export let lastActionName = Symbol('last-action-name')
+
+let uid = 0
+let actionHook = Symbol('action-hook')
+
+export function onAction($store, listener) {
+  $store[actionHook] = (id, actionName, args) => {
+    let errorListeners = {}
+    let endListeners = {}
+    listener({
+      actionName,
+      args,
+      id,
+      onEnd: l => {
+        ;(endListeners[id] || (endListeners[id] = [])).push(l)
+      },
+      onError: l => {
+        ;(errorListeners[id] || (errorListeners[id] = [])).push(l)
+      }
+    })
+    return [
+      error => {
+        if (errorListeners[id]) {
+          for (let l of errorListeners[id]) l({ error })
+        }
+      },
+      () => {
+        if (endListeners[id]) {
+          for (let l of endListeners[id]) l()
+          delete errorListeners[id]
+          delete endListeners[id]
+        }
+      }
+    ]
+  }
+
+  return () => {
+    delete $store[actionHook]
+  }
+}
+
+export function action($store, actionName, cb) {
+  return (...args) => {
+    let id = ++uid
+    let tracker = { ...$store }
+    tracker.set = (...setArgs) => {
+      $store[lastActionName] = actionName
+      $store[lastActionId] = id
+      $store.set(...setArgs)
+      delete $store[lastActionName]
+      delete $store[lastActionId]
+    }
+    if ($store.setKey) {
+      tracker.setKey = (...setArgs) => {
+        $store[lastActionName] = actionName
+        $store[lastActionId] = id
+        $store.setKey(...setArgs)
+        delete $store[lastActionName]
+        delete $store[lastActionId]
+      }
+    }
+    let onEnd, onError
+    if ($store[actionHook]) {
+      ;[onError, onEnd] = $store[actionHook](id, actionName, args)
+    }
+    let result = cb(tracker, ...args)
+    if (result instanceof Promise) {
+      let endTask = startTask()
+      return result
+        .catch(error => {
+          if (onError) onError(error)
+          throw error
+        })
+        .finally(() => {
+          endTask()
+          if (onEnd) onEnd()
+        })
+    }
+    if (onEnd) onEnd()
+    return result
+  }
+}

build-logger/index.d.ts

@@ -1,6 +1,11 @@
 import type { AnyStore, Store, StoreValue } from 'nanostores'
 
 interface LoggerOptionsMessages {
+  /**
+   * Disable action logs.
+   */
+  action?: boolean
+
   /**
    * Disable change logs.
    */
@@ -18,6 +23,11 @@ interface LoggerOptionsMessages {
 }
 
 export interface LoggerOptions {
+  /**
+   * Disable logs of actions with a specific name.
+   */
+  ignoreActions?: string[]
+
   /**
    * Disable specific types of logs.
    */
@@ -29,13 +39,33 @@ interface EventPayloadBase {
 }
 
 interface EventChangePayload extends EventPayloadBase {
+  actionId?: number
+  actionName?: string
   changed?: keyof StoreValue<Store>
   newValue: any
   oldValue?: any
   valueMessage?: string
 }
 
+interface EventActionPayload extends EventPayloadBase {
+  actionId: number
+  actionName: string
+}
+
+interface EventActionStartPayload extends EventActionPayload {
+  args: any[]
+}
+
+interface EventActionErrorPayload extends EventActionPayload {
+  error: Error
+}
+
 interface BuildLoggerEvents {
+  action?: {
+    end?: (payload: EventActionPayload) => void
+    error?: (payload: EventActionErrorPayload) => void
+    start?: (payload: EventActionStartPayload) => void
+  }
   change?: (payload: EventChangePayload) => void
   mount?: (payload: EventPayloadBase) => void
   unmount?: (payload: EventPayloadBase) => void
@@ -57,13 +87,30 @@ interface BuildLoggerEvents {
  *     console.log(`${storeName} was unmounted`)
  *   },
  *
- *   change: ({ changed, newValue, oldValue, valueMessage }) => {
+ *   change: ({ actionName, changed, newValue, oldValue, valueMessage }) => {
  *     let message = `${storeName} was changed`
  *     if (changed) message += `in the ${changed} key`
  *     if (oldValue) message += `from ${oldValue}`
  *     message += `to ${newValue}`
+ *     if (actionName) message += `by action ${actionName}`
  *     console.log(message, valueMessage)
- *   }
+ *   },
+ *
+ *   action: {
+ *     start: ({ actionName, args }) => {
+ *       let message = `${actionName} was started`
+ *       if (args.length) message += 'with arguments'
+ *       console.log(message, args)
+ *     },
+ *
+ *     error: ({ actionName, error }) => {
+ *       console.log(`${actionName} was failed`, error)
+ *     },
+ *
+ *     end: ({ actionName }) => {
+ *       console.log(`${actionName} was ended`)
+ *     }
+ * })
  * ```
  *
  * @param store Any Nano Store