trisgeist 0.1.0

package/.claude/settings.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(bunx tsc *)",
+      "Bash(npm search *)"
+    ]
+  }
+}

package/CONTRIBUTING.md

@@ -0,0 +1,16 @@
+# Contributing
+
+## Adding a framework binding
+
+1. Create `src/<framework>.ts` exporting your hook/adapter (e.g. `src/vue.ts`, `src/svelte.ts`)
+2. Add an export entry in `package.json`:
+   ```json
+   "./<framework>": {
+     "types": "./dist/src/<framework>.d.ts",
+     "import": "./dist/src/<framework>.js"
+   }
+   ```
+3. Add the directory to `.npmignore` if you add any framework-specific source folders outside `src/`
+4. Add `src/<framework>.ts` to `tsconfig.json` `include` if it lives outside `src/` (files inside `src/` are already covered)
+
+The core (`src/Notifier.ts`) has no framework dependencies — keep it that way.

package/LICENSE

@@ -0,0 +1,13 @@
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+                    Version 2, December 2004
+
+ Copyright (C) 2004 Sam Hocevar <sam@hocevar.net>
+
+ Everyone is permitted to copy and distribute verbatim or modified
+ copies of this license document, and changing it is allowed as long
+ as the name is changed.
+
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. You just DO WHAT THE FUCK YOU WANT TO.

package/README.md

@@ -0,0 +1,166 @@
+# trisgeist
+
+small simple global state management library. class-based stores, selector subscriptions, derived state, redux devtools. inspired by flutter's `ChangeNotifier` and riverpod.
+
+## install
+
+```bash
+bun add trisgeist
+# or
+npm install trisgeist
+```
+
+## basic usage
+
+extend `Notifier`, override `build()` to return your initial state, expose actions as methods.
+
+```ts
+import { Notifier } from "trisgeist";
+
+type CounterState = { count: number };
+
+class CounterNotifier extends Notifier<CounterState> {
+  override build() {
+    return { count: 0 };
+  }
+
+  increment() {
+    this.setState({ count: this.state.count + 1 });
+  }
+}
+
+export const counterNotifier = new CounterNotifier();
+```
+
+then in your component:
+
+```tsx
+import { useWatch } from "trisgeist/react";
+import { counterNotifier } from "./counterNotifier";
+
+export function Counter() {
+  const { count } = useWatch(counterNotifier, (o) => o.state);
+
+  return (
+    <button onClick={() => counterNotifier.increment()}>
+      clicked {count} times
+    </button>
+  );
+}
+```
+
+the selector `(o) => o.state.count` means the component only re-renders when `count` changes, not on any unrelated state update.
+
+> **note:** `useWatch` lives at `trisgeist/react` rather than the
+> root export. this keeps the door open for other framework bindings
+> (e.g. `trisgeist/vue`) without name collisions.
+
+## the rules
+
+- **always override `build()`** to return your initial state. don't also
+  assign `state = {...}` as a class field — class fields run *after* the
+  constructor body, so it'll silently overwrite whatever `build()` returned.
+- **`state` is settable**, but every direct assignment must be followed by
+  `notifyListeners()` (or use `setState`/`scheduleNotify`, which call it for
+  you). if you set `state` directly and don't notify, subscribers won't update.
+
+## derived stores
+
+use `watch()` inside `build()` to make a store that recomputes when other stores change — same idea as riverpod's `ref.watch`.
+
+```ts
+class FilteredEventsNotifier extends Notifier<Event[]> {
+  override build() {
+    const events = this.watch(eventsNotifier, (o) => o.state);
+    const filters = this.watch(filtersNotifier, (o) => o.state);
+    return events.filter((e) =>
+      filters.category === "all" || e.category === filters.category
+    );
+  }
+}
+
+export const filteredEventsNotifier = new FilteredEventsNotifier();
+```
+
+when `filtersNotifier` or `eventsNotifier` updates, `build()` reruns automatically. no wiring needed.
+
+> **note:** dependencies declared with `watch()` must be static — call
+> `watch()` on the same stores, in the same order, every time `build()` runs.
+> only the first call (during construction) actually registers subscriptions,
+> so conditional `watch()` calls won't be tracked correctly afterward.
+
+## debounced updates
+
+if you're getting a burst of updates (websocket events, stream data) and don't want a re-render for each one, assign `this.state` directly (no merge) and call `scheduleNotify()` instead of `setState`:
+
+```ts
+class MessagesNotifier extends Notifier<Message[]> {
+  override debounceDuration = 50; // default is 100ms
+
+  override build() {
+    return [] as Message[];
+  }
+
+  onMessage(msg: Message) {
+    this.state = [...this.state, msg];
+    this.scheduleNotify(); // batches into one re-render once the burst settles
+  }
+}
+```
+
+`scheduleNotify()` resets a timer on each call and only fires `notifyListeners()` once things settle. unlike `setState`, it does **not** merge — set `this.state` to the full new value yourself first.
+
+## reading from other stores
+
+stores are just singletons, import and read from them anywhere:
+
+```ts
+class CartNotifier extends Notifier<CartState> {
+  checkout() {
+    const { currency } = settingsNotifier.state;
+    this.setState({ total: calculateTotal(this.state.items, currency) });
+  }
+}
+```
+
+## which update method to use
+
+| method | when |
+|---|---|
+| `setState(partial)` | shallow merge + notify immediately — use this for almost everything |
+| `this.state = ...` + `notifyListeners()` | full state replacement, then notify |
+| `this.state = ...` + `scheduleNotify()` | full replacement, debounced notify, for burst updates |
+
+## devtools
+
+connects to [redux devtools](https://github.com/reduxjs/redux-devtools) automatically if you have the extension installed. each store shows up as its own instance in the dropdown. time travel works on source stores — derived ones recompute naturally.
+
+no config needed, just install the extension.
+
+## react native
+
+works fine, `useSyncExternalStore` is react core not web-specific.
+
+## api
+
+### `Notifier<TState>` — `trisgeist`
+
+| member | description |
+|---|---|
+| `state` | current state, settable — direct assignment requires a `notifyListeners()`/`scheduleNotify()` call after |
+| `build()` | **must override.** return initial state here, call `watch()` to declare deps |
+| `setState(partial)` | shallow merge + notify |
+| `notifyListeners()` | manually flush listeners |
+| `scheduleNotify()` | debounced flush |
+| `debounceDuration` | debounce ms, default `100`, override per store |
+| `watch(store, selector)` | declare a static dep inside `build()`, reruns build when it changes |
+| `subscribe(listener, selector)` | raw subscription, returns unsub fn |
+
+### `useWatch(store, selector?)` — `trisgeist/react`
+
+```ts
+import { useWatch } from "trisgeist/react";
+
+const state = useWatch(myNotifier); // whole state, re-renders on any change
+const count = useWatch(myNotifier, (o) => o.state.count); // only re-renders when count changes
+```

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { Notifier } from "./src/Notifier";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+export { Notifier } from "./src/Notifier";

package/index.ts

@@ -0,0 +1 @@
+export { Notifier } from "./src/Notifier";

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "trisgeist",
+  "license": "WTFPL",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "module": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/src/react.d.ts",
+      "import": "./dist/src/react.js"
+    }
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/react": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5",
+    "react": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "bunx tsc",
+    "prepare": "bunx tsc"
+  }
+}