chain-store 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aleksandr Gurianov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,183 @@
-# Temporary Holding Version
+# chain-store
+
+**A simple event-based state manager.** It works with just two functions!
+
+```
+/** Any package manager */
+
+> npm install chain-store
+```
+
+
+### Actions
+
+Create an action, trigger it, and subscribe or unsubscribe to updates:
+```ts
+import { createAction } from "chain-store";
+import type { Action, Subscription } from "chain-store";
+
+/* Create */
+const setNumber: Action<number> = createAction<number>()
+
+/* Subscribe */
+const subscription: Subscription = setNumber.watch(console.log)
+
+/* Trigger */
+setNumber(42);    // -> 42
+
+/* Unsubscribe */
+subscription.dispose();
+```
+
+
+### Chaining
+Every action can be chained with other actions using the `.map` and `.filter` methods. 
+These methods take a callback as input. The callback returns a new value for `.map` 
+and a boolean for `.filter`. Callbacks can be asynchronous.
+
+```ts
+const asString = setNumber.map((n: number) => n.toString());
+const asObject = asString.map(async (s: string) => ({ value: s }));
+const negativeOnly = setNumber.filter((n: number) => n < 0)
+const squareRoot = setNumber.filter((n: number) => n >= 0).map(Math.sqrt)
+```
+
+
+All actions in a chain are connected, and triggering any of them will trigger 
+the others. Each action triggers in the order in which it was chained. Subscriptions 
+fire after all callbacks for that action have resolved, so asynchronous callbacks 
+can make the process take longer.
+
+```ts
+/* Subscribe to see the output */
+asString.watch(s => console.log("asString", s));
+asObject.watch(o => console.log("asObject", o));
+negativeOnly.watch(n => console.log("negativeOnly", n));
+squareRoot.watch(n => console.log("squareRoot", n));
+
+asObject(16);     // -> "asString", "16"
+                  // -> "squareRoot", 4
+                  // -> "asObject", { value: "16" } */
+
+/* "negativeOnly" is filtered out */
+
+
+squareRoot(-10);  // -> "asString", "-10"
+                  // -> "negativeOnly", -10
+                  // -> "asObject", { value: "-10" }
+
+/* "squareRoot" is filtered out, even though it was the original trigger */
+```
+
+Of course, you can choose which actions to watch. And there’s no need to create 
+each action separately:
+
+```ts
+const chainAction = createAction<number>()
+  .filter(n > 0)
+  .map(n => Math.pow(n, 2))
+  .filter(n < 1000)
+  .map(n => `Power of two is: ${n}`)
+```
+
+
+### Async Actions
+An async action is the end of a chain. The main difference between an async action 
+and a regular action is that an async action has `.done`, `.fail`, and `.finally` methods, 
+which can be watched just like triggers.
+
+Create an async action by chaining an action with the `.target` method:
+
+```ts
+import { createAction } from "chain-store";
+import type { AsyncAction } from "chain-store";
+
+const asyncAction: AsyncAction<number, { data: number }> 
+  = createAction<number>().target(async (payload: number) => ({ data: payload }))
+
+asynsAction.watch((payload: number) => 
+  console.log("start", payload));
+
+asyncActions.done.watch((result: { data: number }, payload: number) => 
+  console.log("done", result, payload));
+
+asyncActions.fail.watch((error: Error, payload: number) => 
+  console.log("fail", error, payload));
+
+asyncActions.finally.watch((payload: number) => 
+  console.log("finally", payload));
+```
+
+Async actions return an `ActionPromise`. It’s like a promise, but it isn’t one. 
+It’s useful when you need to wait for an async action to complete before doing 
+something elsewhere in the app, outside the store.
+
+```ts
+const actionPromise = asyncAction(20);
+
+actionPromise.done((result: { data: number }, payload: number) => {
+  console.log(result, params);        // -> { data: 20 }, 20, "done"
+  console.log(actionPromise.state);   // -> "done"
+});
+
+console.log(actionPromise.state);     // -> "pending"
+
+
+```
+
+**Note I:** An async action fails only if its own callback is rejected. Any other 
+rejection earlier in the chain simply stops further execution, so no fail event 
+occurs in that case.
+
+### Store
+
+```ts
+import { createStore, createAction } from "chain-store";
+
+type State = { name: string, age: number };
+const initialState: State = { name: "John", age: 30 };
+
+
+const changeName = createAction<string>();
+
+/* Create a store */
+const store = createStore<State>(initialState);
+
+/* Subscribe the store to an action */
+store.on(changeName, (state: State, name: string) => {
+  return { ...state, name: name };
+});
+
+/* Subscribe to store changes */
+const subscription = store.watch((state: State) => console.log(`My name is ${state.name}`));
+
+changeName("Alex");  // -> "My name is Alex"
+
+/* Unsubscribe from store changes */
+subscription.dispose();
+
+/* Unsubscribe the store from the action */
+store.off(changeName)
+```
+
+The store also works with mutable state, if needed:
+
+```ts
+const setAge = createAction<number>();
+
+store.on(setAge, (state: State, age: number) => {
+  state.age = age; /* State mutation */
+  return state;
+});
+
+/* Subscribe to partial state updates */
+store
+  .map((state: State) => state.age)
+  .watch((age: number) => console.log(`Now I'm ${age}`));
+
+setAge(42);  // -> "Now I'm 42"
+
+/* The store.watch() subscription won't be triggered
+   because the state is the same object */
+```
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './store';
+export * from './types';

package/dist/index.es.js

@@ -0,0 +1,201 @@
+const O = () => w([]), k = (c) => {
+  const t = [], r = [], i = b();
+  let n = [], s = !1, e = c;
+  const a = (o) => {
+    var l, p;
+    const d = t.findIndex(([h]) => h === o);
+    d >= 0 && ((p = (l = t[d]) == null ? void 0 : l[1]) == null || p.dispose(), t.splice(d, 1));
+  }, u = {
+    on: (o, d) => (a(o), t.push([
+      o,
+      o.watch((...l) => {
+        s = !0;
+        const p = r.map(([m]) => m(e)), h = d(e, ...l);
+        h !== e && (e = h, i.emit("watch")(e)), r.forEach(([m, P], j) => {
+          const y = m(e);
+          y !== (p == null ? void 0 : p[j]) && P(y);
+        }), s = !1, n.forEach((m) => m()), n = [];
+      })
+    ]), u),
+    off: (o) => (a(o), u),
+    map: (o) => ({
+      getState: () => o(e),
+      watch: (d) => (r.push([o, d]), {
+        dispose: () => {
+          const l = () => {
+            const p = r.findIndex(
+              (h) => h[0] === o && h[1] === d
+            );
+            p >= 0 && r.splice(p, 1);
+          };
+          if (s) return n.push(l);
+          l();
+        }
+      })
+    }),
+    getState: () => e,
+    watch: (o) => {
+      i.init("watch").watch(o);
+    }
+  };
+  return u;
+}, w = (c, t) => {
+  const r = b(), i = (e) => {
+    r.emit("watch")(e);
+  }, n = (e) => {
+    try {
+      S(i, t)(e);
+    } catch {
+    }
+  };
+  return c.push(n), Object.assign((e) => {
+    c.forEach((a) => a(e));
+  }, {
+    ...r.init("watch"),
+    map: (e) => w(c, {
+      map: t != null && t.filter || t != null && t.map ? S(e, t, !0) : e
+    }),
+    filter: (e) => w(c, {
+      ...t,
+      filter: t != null && t.filter ? x(e, t.filter) : e
+    }),
+    target: (e, a) => t != null && t.filter ? E(c, {
+      map: async (u) => {
+        const o = t != null && t.map ? await t.map(u) : u;
+        if (!await t.filter(
+          o
+        )) throw new Error();
+        return o;
+      },
+      target: e,
+      options: a
+    }) : E(c, {
+      map: t == null ? void 0 : t.map,
+      target: e,
+      options: a
+    })
+  });
+}, E = (c, t) => {
+  const r = b(), i = [], n = async (a, u) => {
+    var p;
+    const o = t.target(a);
+    if (!(o instanceof Promise)) {
+      r.emit("watch")(a), r.emit("done")(o, a), u == null || u.done(o, a);
+      return;
+    }
+    const d = i.includes(o), l = ((p = t.options) == null ? void 0 : p.skipDuplicates) !== !1;
+    !d && l && i.push(o), (!d || !l) && r.emit("watch")(a), window.requestAnimationFrame(async () => {
+      try {
+        const h = await o;
+        (!d || !l) && r.emit("done")(h, a), u == null || u.done(h, a);
+      } catch (h) {
+        (!d || !l) && r.emit("fail")(h, a), u == null || u.fail(h, a);
+      } finally {
+        if (!d || !l)
+          r.emit("finally")(a);
+        else {
+          const h = i.findIndex((m) => m === o);
+          h >= 0 && i.splice(h, 1);
+        }
+        u == null || u.finish(a);
+      }
+    });
+  }, s = async (a, u) => {
+    if (!t.map) return await n(a, u);
+    try {
+      const o = await t.map(a);
+      await n(o, u);
+    } catch {
+    }
+  };
+  return c.push(s), Object.assign((a) => {
+    const { events: u, methods: o } = A();
+    return c.forEach((d) => {
+      s === d ? s(a, u) : d(a);
+    }), o;
+  }, {
+    ...r.init("watch"),
+    done: r.init("done"),
+    fail: r.init("fail"),
+    finish: r.init("finish")
+  });
+}, x = (c, t, r) => (i) => {
+  const n = (t == null ? void 0 : t(i)) ?? !0, s = (e) => {
+    if (!e && r) throw new Error();
+    return e && c(i);
+  };
+  return n instanceof Promise ? n.then(s) : s(n);
+}, S = (c, t, r) => (i) => {
+  var s;
+  const n = ((s = t == null ? void 0 : t.map) == null ? void 0 : s.call(t, i)) ?? i;
+  return n instanceof Promise ? n.then(x(c, t == null ? void 0 : t.filter, r)).catch(() => {
+    if (r) throw new Error();
+    return !1;
+  }) : x(c, t == null ? void 0 : t.filter, r)(n);
+}, A = (c) => {
+  const t = {}, r = c ?? {
+    state: "pending",
+    stored: {},
+    set: (s) => {
+      r.state = s;
+    },
+    controller: new I(() => r.state)
+  }, i = {
+    done: (s, e) => {
+      var a;
+      r.stored.result = s, r.set("done"), (a = t.done) == null || a.call(t, s, e);
+    },
+    fail: (s, e) => {
+      var a;
+      r.stored.error = s, r.set("fail"), (a = t.fail) == null || a.call(t, s, e);
+    },
+    finish: (s) => {
+      var e;
+      r.stored.params = s, (e = t.finish) == null || e.call(t, s);
+    }
+  }, n = (s, ...e) => t[s] ? void 0 : (a) => (t[s] = a, r.state !== "pending" && a(...e.map((u) => r.stored[u])), A(r).methods);
+  return {
+    events: i,
+    methods: Object.assign(r.controller, {
+      done: n("done", "result", "params"),
+      fail: n("fail", "error", "params"),
+      finish: n("finish", "params")
+    })
+  };
+};
+class I {
+  constructor(t) {
+    this.getState = t;
+  }
+  get state() {
+    return this.getState();
+  }
+}
+const b = () => {
+  const c = {}, t = (i, n) => {
+    var s;
+    (s = c[i]) != null && s.includes(n) && (c[i] = c[i].filter(
+      (e) => e !== n
+    ));
+  }, r = (i, n) => {
+    var s;
+    (s = c[i]) != null && s.includes(n) || (c[i] = [...c[i] ?? [], n]);
+  };
+  return {
+    init: (i) => ({
+      watch: (n) => (r(i, n), {
+        dispose: () => t(i, n)
+      })
+    }),
+    emit: (i) => (...n) => {
+      var s;
+      (s = c[i]) == null || s.forEach(
+        (e) => e(...n)
+      );
+    }
+  };
+};
+export {
+  O as createAction,
+  k as createStore
+};

package/dist/index.umd.js

@@ -0,0 +1 @@
+(function(m,b){typeof exports=="object"&&typeof module<"u"?b(exports):typeof define=="function"&&define.amd?define(["exports"],b):(m=typeof globalThis<"u"?globalThis:m||self,b(m["chain-store"]={}))})(this,function(m){"use strict";const b=()=>y([]),P=c=>{const t=[],r=[],a=S();let i=[],s=!1,e=c;const n=o=>{var l,p;const d=t.findIndex(([h])=>h===o);d>=0&&((p=(l=t[d])==null?void 0:l[1])==null||p.dispose(),t.splice(d,1))},u={on:(o,d)=>(n(o),t.push([o,o.watch((...l)=>{s=!0;const p=r.map(([w])=>w(e)),h=d(e,...l);h!==e&&(e=h,a.emit("watch")(e)),r.forEach(([w,I],T)=>{const j=w(e);j!==(p==null?void 0:p[T])&&I(j)}),s=!1,i.forEach(w=>w()),i=[]})]),u),off:o=>(n(o),u),map:o=>({getState:()=>o(e),watch:d=>(r.push([o,d]),{dispose:()=>{const l=()=>{const p=r.findIndex(h=>h[0]===o&&h[1]===d);p>=0&&r.splice(p,1)};if(s)return i.push(l);l()}})}),getState:()=>e,watch:o=>{a.init("watch").watch(o)}};return u},y=(c,t)=>{const r=S(),a=e=>{r.emit("watch")(e)},i=e=>{try{f(a,t)(e)}catch{}};return c.push(i),Object.assign(e=>{c.forEach(n=>n(e))},{...r.init("watch"),map:e=>y(c,{map:t!=null&&t.filter||t!=null&&t.map?f(e,t,!0):e}),filter:e=>y(c,{...t,filter:t!=null&&t.filter?x(e,t.filter):e}),target:(e,n)=>t!=null&&t.filter?E(c,{map:async u=>{const o=t!=null&&t.map?await t.map(u):u;if(!await t.filter(o))throw new Error;return o},target:e,options:n}):E(c,{map:t==null?void 0:t.map,target:e,options:n})})},E=(c,t)=>{const r=S(),a=[],i=async(n,u)=>{var p;const o=t.target(n);if(!(o instanceof Promise)){r.emit("watch")(n),r.emit("done")(o,n),u==null||u.done(o,n);return}const d=a.includes(o),l=((p=t.options)==null?void 0:p.skipDuplicates)!==!1;!d&&l&&a.push(o),(!d||!l)&&r.emit("watch")(n),window.requestAnimationFrame(async()=>{try{const h=await o;(!d||!l)&&r.emit("done")(h,n),u==null||u.done(h,n)}catch(h){(!d||!l)&&r.emit("fail")(h,n),u==null||u.fail(h,n)}finally{if(!d||!l)r.emit("finally")(n);else{const h=a.findIndex(w=>w===o);h>=0&&a.splice(h,1)}u==null||u.finish(n)}})},s=async(n,u)=>{if(!t.map)return await i(n,u);try{const o=await t.map(n);await i(o,u)}catch{}};return c.push(s),Object.assign(n=>{const{events:u,methods:o}=A();return c.forEach(d=>{s===d?s(n,u):d(n)}),o},{...r.init("watch"),done:r.init("done"),fail:r.init("fail"),finish:r.init("finish")})},x=(c,t,r)=>a=>{const i=(t==null?void 0:t(a))??!0,s=e=>{if(!e&&r)throw new Error;return e&&c(a)};return i instanceof Promise?i.then(s):s(i)},f=(c,t,r)=>a=>{var s;const i=((s=t==null?void 0:t.map)==null?void 0:s.call(t,a))??a;return i instanceof Promise?i.then(x(c,t==null?void 0:t.filter,r)).catch(()=>{if(r)throw new Error;return!1}):x(c,t==null?void 0:t.filter,r)(i)},A=c=>{const t={},r=c??{state:"pending",stored:{},set:s=>{r.state=s},controller:new O(()=>r.state)},a={done:(s,e)=>{var n;r.stored.result=s,r.set("done"),(n=t.done)==null||n.call(t,s,e)},fail:(s,e)=>{var n;r.stored.error=s,r.set("fail"),(n=t.fail)==null||n.call(t,s,e)},finish:s=>{var e;r.stored.params=s,(e=t.finish)==null||e.call(t,s)}},i=(s,...e)=>t[s]?void 0:n=>(t[s]=n,r.state!=="pending"&&n(...e.map(u=>r.stored[u])),A(r).methods);return{events:a,methods:Object.assign(r.controller,{done:i("done","result","params"),fail:i("fail","error","params"),finish:i("finish","params")})}};class O{constructor(t){this.getState=t}get state(){return this.getState()}}const S=()=>{const c={},t=(a,i)=>{var s;(s=c[a])!=null&&s.includes(i)&&(c[a]=c[a].filter(e=>e!==i))},r=(a,i)=>{var s;(s=c[a])!=null&&s.includes(i)||(c[a]=[...c[a]??[],i])};return{init:a=>({watch:i=>(r(a,i),{dispose:()=>t(a,i)})}),emit:a=>(...i)=>{var s;(s=c[a])==null||s.forEach(e=>e(...i))}}};m.createAction=b,m.createStore=P,Object.defineProperty(m,Symbol.toStringTag,{value:"Module"})});

package/dist/store.d.ts

@@ -0,0 +1,3 @@
+import { Action, Store } from './types';
+export declare const createAction: <Input>() => Action<Input, Input>;
+export declare const createStore: <State>(initialState: State) => Store<State>;

package/dist/types.d.ts

@@ -0,0 +1,48 @@
+type ActionCall<Params, Result extends unknown = void> = (params: Params) => Result;
+export type ActionPromise<Params, Result, Error, Methods = ActionPromiseMethods<Params, Result, Error>, Remaining extends keyof Methods = keyof Methods> = {
+    state: "pending" | "done" | "fail";
+} & {
+    [K in Remaining]: (fn: Methods[K]) => ActionPromise<Params, Result, Error, Methods, Exclude<Remaining, K>>;
+};
+export type ActionPromiseMethods<Params, Result, Error> = {
+    done: (result: Result, params: Params) => void;
+    fail: (error: Error, params: Params) => void;
+    finish: (params: Params) => void;
+};
+export type Args<Params> = Params extends Array<unknown> ? Params : [Params];
+export type AsyncActionOptions = {
+    skipDuplicates?: boolean;
+};
+export type ChainFn<Input, Output> = (params: Input) => Output | Promise<Output>;
+export interface Subscription {
+    dispose: VoidFunction;
+}
+export interface Unit<Params> {
+    watch: (watcher: (...args: Args<Params>) => void) => Subscription;
+}
+export interface Action<Input, Output = Input> extends ActionCall<Input>, Unit<Input> {
+    filter: (fn: ChainFn<Output, boolean>) => Action<Input, Output>;
+    map: <Mapped>(fn: ChainFn<Output, Mapped>) => Action<Input, Mapped>;
+    target: <Result, Err = Error>(fn: ChainFn<Output, Result>) => AsyncAction<Input, Result, Output, Err>;
+}
+export interface AsyncAction<Input, Result, Params = Input, Err = Error> extends ActionCall<Input, ActionPromise<Params, Result, Err>>, Unit<Params> {
+    done: {
+        watch: (watcher: (result: Result, params: Params) => void) => Subscription;
+    };
+    fail: {
+        watch: (watcher: (error: Err, params: Params) => void) => Subscription;
+    };
+    finish: {
+        watch: (watcher: (params: Params) => void) => Subscription;
+    };
+}
+export interface ReadStore<State> {
+    watch: (watcher: (state: State) => void) => Subscription;
+    getState: () => State;
+}
+export interface Store<State> extends ReadStore<State> {
+    on: <T>(action: Unit<T>, f: (state: State, ...args: Args<T>) => State) => Store<State>;
+    off: <T>(action: Unit<T>) => Store<State>;
+    map: <Part>(mapper: (state: State) => Part) => ReadStore<Part>;
+}
+export {};

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "chain-store",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "Simple event-based state manager",
+  "version": "0.0.2",
+  "author": {
+    "name": "Aleksandr Gurianov",
+    "url": "http://golova.pro"
+  },
+  "homepage": "https://graverok.github.io/chain-store",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/graverok/chain-store.git"
+  },
+  "bugs": {
+    "url": "https://github.com/graverok/chain-store/issues"
+  },
+  "license": "MIT",
+  "module": "dist/index.es.js",
+  "main": "dist/index.udm.js",
+  "types": "dist/index.d.ts",
+  "keywords": [
+    "business-logic",
+    "event-based",
+    "state-management",
+    "state-manager",
+    "chain-store"
+  ],
+  "devDependencies": {
+    "@babel/core": "^7.2.2",
+    "@babel/preset-env": "^7.2.3",
+    "@babel/preset-typescript": "^7.23.3",
+    "@types/node": "^22.8.6",
+    "prettier": "^3.1.1",
+    "typescript": "^5.3.3",
+    "vite": "5.4.6",
+    "vite-plugin-dts": "^4.0.3",
+    "vite-tsconfig-paths": "^4.3.1"
+  },
+  "scripts": {
+    "build": "vite build"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ]
+}