@zeix/cause-effect 1.0.0 → 1.0.1

package/.github/copilot-instructions.md

@@ -10,7 +10,7 @@ Cause & Effect is a reactive state management library for JavaScript/TypeScript
 - **Nodes**: StateNode (source + equality), MemoNode (source + sink), TaskNode (source + sink + async), EffectNode (sink + owner)
 - **Edges**: Doubly-linked list connecting sources to sinks
 - **Operations**: `link()` creates edges, `propagate()` flags sinks dirty, `flush()` runs queued effects, `batch()` defers flushing
-- **Flags**: FLAG_CLEAN, FLAG_CHECK, FLAG_DIRTY, FLAG_RUNNING for efficient dirty checking
+- **Flags**: FLAG_CLEAN, FLAG_CHECK, FLAG_DIRTY, FLAG_RUNNING, FLAG_RELINK for efficient dirty checking
 
 ### Signal Types (all in `src/nodes/`)
 - **State** (`createState`): Mutable signals for values (`get`, `set`, `update`)
@@ -36,6 +36,7 @@ Cause & Effect is a reactive state management library for JavaScript/TypeScript
 - `src/nodes/list.ts` - createList, isList, List type
 - `src/nodes/collection.ts` - createCollection, isCollection, Collection type, deriveCollection (internal)
 - `src/nodes/slot.ts` - createSlot, isSlot, Slot type
+- `src/signal.ts` - Polymorphic factories (createSignal, createMutableSignal, createComputed) and type predicates (isSignal, isMutableSignal, isComputed)
 - `src/util.ts` - Utility functions and type checks
 - `index.ts` - Entry point / main export file
 

package/.zed/settings.json

@@ -1,3 +1,26 @@
 {
-  "project_name": "Cause & Effect"
+	"project_name": "Cause & Effect",
+	"languages": {
+		"TypeScript": {
+			"language_servers": ["!eslint", "..."],
+			"code_actions_on_format": {
+				"source.fixAll.biome": true,
+				"source.organizeImports.biome": true,
+			},
+		},
+		"JavaScript": {
+			"language_servers": ["!eslint", "..."],
+			"code_actions_on_format": {
+				"source.fixAll.biome": true,
+				"source.organizeImports.biome": true,
+			},
+		},
+		"TSX": {
+			"language_servers": ["!eslint", "..."],
+			"code_actions_on_format": {
+				"source.fixAll.biome": true,
+				"source.organizeImports.biome": true,
+			},
+		},
+	},
 }

package/ARCHITECTURE.md

@@ -178,7 +178,7 @@ Creates an ownership scope without an effect. The scope becomes `activeOwner` du
 
 ### State (`src/nodes/state.ts`)
 
-**Graph node**: `MemoNode<T>` (source + sink, single delegated dependency)
+**Graph node**: `StateNode<T>` (source only)
 
 A mutable value container. The simplest signal type — `get()` links and returns the value, `set()` validates, calls `setState()`, which propagates changes to dependents.
 

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.0.1
+
+### Added
+
+- **`cause-effect` skill for consumer projects**: New Claude Code skill with self-contained API knowledge in `references/` — no library source access required. Covers three workflows: `use-api`, `debug`, and `answer-question`.
+- **`README.md` Utilities section**: Documents the previously undocumented `createSignal`, `createMutableSignal`, `createComputed` factories and `isSignal`, `isMutableSignal`, `isComputed` predicates exported from `index.ts`.
+
+### Changed
+
+- **`cause-effect-dev` skill restructured**: Refactored to progressive disclosure pattern with separate `workflows/` and `references/` modules. Scoped explicitly to library development; external references to `REQUIREMENTS.md`, `ARCHITECTURE.md`, and `src/` are now clearly library-repo-only.
+- **Documentation alignment**: Corrected wrong graph node type for `State` in `ARCHITECTURE.md`; added missing `FLAG_RELINK` and `src/signal.ts` to `copilot-instructions.md`; updated `REQUIREMENTS.md` stability section to reflect 1.0 release; completed and corrected JSDoc across `Sensor`, `Memo`, `Store`, `List`, `Collection`, and utility types. No runtime behaviour changed.
+- **TypeScript 6 compatibility**: Added `erasableSyntaxOnly` to `tsconfig.json` (requires TS ≥5.8); replaced `@types/bun` with `bun-types` directly and added `"types": ["bun-types"]` to `tsconfig.json` to fix module resolution under TypeScript 6.
+- **Package management cleanup**: Added `typescript` to `devDependencies` (was only in `peerDependencies`, causing stale version installs); updated `peerDependencies` range to `>=5.8.0`; removed `package-lock.json` and gitignored npm/yarn/pnpm lockfiles — Bun is required for development.
+- **Zed editor configuration**: Disabled ESLint language server for JS/TS/TSX in `.zed/settings.json` — project uses Biome for linting.
+
 ## 1.0.0
 
 ### Changed

package/README.md

@@ -399,6 +399,47 @@ createEffect(() => {
 })
 ```
 
+### Utilities
+
+Polymorphic factories and type predicates for generic and library-author code.
+
+**`createSignal(value)`** converts any value to its corresponding signal type:
+
+```ts
+import { createSignal } from '@zeix/cause-effect'
+
+createSignal(0)                          // → State<number>
+createSignal([1, 2, 3])                  // → List<number>
+createSignal({ x: 0 })                   // → Store<{ x: number }>
+createSignal(() => x.get() * 2)          // → Memo<number>
+createSignal(async (_, s) =>
+  fetch('/api', { signal: s }).then(r => r.json()))  // → Task<Response>
+```
+
+If the value is already a signal, it is returned unchanged.
+
+**`createMutableSignal(value)`** is the same, but restricted to mutable signals — returns `State`, `Store`, or `List`. Throws `InvalidSignalValueError` if passed a function or a read-only signal.
+
+**`createComputed(callback, options?)`** creates a `Memo` or `Task` by detecting whether the callback is async:
+
+```ts
+import { createComputed } from '@zeix/cause-effect'
+
+const doubled = createComputed(() => count.get() * 2)
+const data    = createComputed(async (_, signal) =>
+  fetch(url.get(), { signal }).then(r => r.json()))
+```
+
+**Type predicates**
+
+| Predicate | True for |
+|---|---|
+| `isSignal(value)` | Any signal (all 9 types) |
+| `isMutableSignal(value)` | `State`, `Store`, `List` — signals with `.set()` and `.update()` |
+| `isComputed(value)` | `Memo`, `Task` — derived signals |
+
+The `MutableSignal<T>` type is the corresponding TypeScript type for `isMutableSignal` — use it as a parameter type in generic code that accepts any writable signal.
+
 ## Choosing the Right Signal
 
 ```

package/REQUIREMENTS.md

@@ -84,11 +84,11 @@ The following are explicitly out of scope and will not be added to the library:
 
 ## Stability
 
-Version 0.18 is the last pre-release before 1.0. The API surface — how signals are created and consumed — is considered stable. From 1.0 onward:
+The library is stable at 1.0.0. The API surface — how signals are created and consumed — will not change except under the following conditions:
 
-- **Breaking changes** are expected only if major new features of the Web Platform shift the optimal way to achieve the goals this library already does.
+- **Breaking changes** only if major new features of the Web Platform shift the optimal way to achieve the goals this library already covers.
 - **New features** are not expected. The signal type set is complete.
-- **Backward compatibility** becomes a concern at 1.0. Prior to that, all known consumers (Le Truc and one other library) are maintained by Zeix AG and can adapt to changes.
+- **Backward compatibility** is maintained from 1.0 onward.
 
 ## Success Criteria
 

package/eslint.config.js

@@ -4,8 +4,9 @@ import tseslint from 'typescript-eslint'
 
 /** @type {import('eslint').Linter.Config[]} */
 export default [
+	// Global ignores to prevent warnings about these files
 	{
-		ignores: ['index.js', '**/*.min.js'],
+		ignores: ['index.js', 'index.dev.js', 'types/**/*.d.ts', '**/*.min.js'],
 	},
 	{
 		files: ['**/*.{js,mjs,cjs,ts}'],

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zeix/cause-effect",
-	"version": "1.0.0",
+	"version": "1.0.1",
 	"author": "Esther Brunner",
 	"type": "module",
 	"main": "index.js",
@@ -8,12 +8,13 @@
 	"types": "types/index.d.ts",
 	"devDependencies": {
 		"@biomejs/biome": "2.4.6",
-		"@types/bun": "latest",
+		"bun-types": "latest",
 		"mitata": "^1.0.34",
-		"random": "^5.4.1"
+		"random": "^5.4.1",
+		"typescript": "latest"
 	},
 	"peerDependencies": {
-		"typescript": "^5.9.3"
+		"typescript": ">=5.8.0"
 	},
 	"description": "Cause & Effect - reactive state management primitives library for TypeScript.",
 	"license": "MIT",

package/skills/cause-effect/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: cause-effect
+description: >
+  Expert guidance for using the @zeix/cause-effect reactive signals library in any project.
+  Use when implementing reactive patterns, debugging unexpected behavior, or answering
+  questions about the public API, signal types, or design decisions. Works in any project
+  that depends on @zeix/cause-effect — all knowledge is embedded, no library source required.
+---
+
+<scope>
+This skill is for **consumer projects** that use `@zeix/cause-effect` as a dependency.
+All domain knowledge is embedded in `references/` — no library source files are required.
+
+For development work on the library itself, use the `cause-effect-dev` skill instead.
+</scope>
+
+<essential_principles>
+**`T extends {}`** — all signal generics exclude `null` and `undefined`. Use wrapper types or sentinel values to represent absence.
+
+**`createEffect` must be inside an owner.** Always wrap effect creation in `createScope` or nest it inside another effect.
+
+**Never guess API shapes or behaviors.** The answers are in `references/`. If the embedded knowledge is insufficient, check the library's README or GUIDE — do not invent behavior.
+</essential_principles>
+
+<intake>
+What kind of task is this?
+
+1. **Use** — implement reactive patterns using the library's public API
+2. **Debug** — investigate unexpected or broken reactive behavior
+3. **Question** — understand the API, which signal to use, or a design decision
+
+**Wait for response before proceeding.**
+</intake>
+
+<routing>
+| Response | Workflow |
+|---|---|
+| 1, "use", "implement", "add", "build", "write" | workflows/use-api.md |
+| 2, "debug", "fix", "broken", "not working", "wrong", "unexpected" | workflows/debug.md |
+| 3, "question", "explain", "how", "why", "what", "which", "when" | workflows/answer-question.md |
+
+**Intent-based routing** (if user provides clear context without selecting):
+- Describes code to write or a feature to add → workflows/use-api.md
+- Describes something not working as expected → workflows/debug.md
+- Asks how something works or which signal to use → workflows/answer-question.md
+
+**After identifying the workflow, read it and follow it exactly.**
+</routing>
+
+<reference_index>
+All in `references/` — all knowledge is self-contained, no external files required:
+
+| File | Contents |
+|---|---|
+| signal-types.md | What each signal is for, when to use each, decision guide |
+| api-facts.md | Key API constraints, core functions, options, callback patterns |
+| non-obvious-behaviors.md | Counterintuitive behaviors with correct vs incorrect examples |
+| error-classes.md | Error classes, trigger conditions, and how to handle them |
+</reference_index>
+
+<workflows_index>
+All in `workflows/`:
+
+| Workflow | Purpose |
+|---|---|
+| use-api.md | Implement reactive patterns using the public API |
+| debug.md | Diagnose and fix unexpected reactive behavior |
+| answer-question.md | Answer questions about the API, signals, or design |
+</workflows_index>

package/skills/cause-effect/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Cause & Effect"
+  short_description: "Expert guidance for using the @zeix/cause-effect reactive signals library in your project"
+  default_prompt: "Use $cause-effect to implement reactive patterns, debug unexpected behavior, or answer questions about the @zeix/cause-effect public API."

package/skills/cause-effect/references/api-facts.md

@@ -0,0 +1,179 @@
+<overview>
+Key API constraints, defaults, and callback patterns for @zeix/cause-effect. All knowledge is
+self-contained — no library source files required. Read this when writing or reviewing any
+code that uses the public API.
+</overview>
+
+<type_constraint>
+**`T extends {}`** — all signal generics exclude `null` and `undefined` at the type level.
+This is intentional: signals always have a value; absence must be modelled explicitly.
+
+```typescript
+// Wrong — TypeScript will reject this
+const count = createState<number | null>(null)
+
+// Correct — use a sentinel or a wrapper type
+const count = createState<number>(0)
+const selected = createState<{ id: string } | { id: never }>({ id: '' })
+```
+</type_constraint>
+
+<core_functions>
+**`createScope(fn)`**
+- Returns a single `Cleanup` function
+- `fn` receives no arguments and may return an optional cleanup
+- Use to group effects and control their shared lifetime
+
+```typescript
+const dispose = createScope(() => {
+  createEffect(() => console.log(count.get()))
+  // all effects inside are disposed when dispose() is called
+})
+dispose() // cleans up everything inside
+```
+
+**`createEffect(fn)`**
+- Returns a `Cleanup` function
+- **Must be called inside an owner** (a `createScope` callback or another `createEffect` callback)
+- Throws `RequiredOwnerError` if called without an active owner
+- Runs `fn` immediately, then re-runs whenever tracked dependencies change
+
+**`batch(fn)`**
+- Defers the reactive flush until `fn` returns
+- Multiple state writes inside `fn` coalesce into a single propagation pass
+- Use when updating several signals that feed the same downstream computation
+
+```typescript
+batch(() => {
+  x.set(1)
+  y.set(2)
+  z.set(3)
+  // only one propagation pass runs after all three writes
+})
+```
+
+**`untrack(fn)`**
+- Runs `fn` without recording dependency edges
+- Reads inside `fn` do not subscribe the current computation to those signals
+- Use to read a signal's current value without creating a reactive dependency
+
+```typescript
+createEffect(() => {
+  const a = reactive.get()           // tracked — effect re-runs when reactive changes
+  const b = untrack(() => other.get()) // untracked — no dependency on other
+  render(a, b)
+})
+```
+
+**`unown(fn)`**
+- Runs `fn` without registering cleanups in the current owner
+- Use in `connectedCallback` and similar DOM lifecycle methods where the DOM —
+  not the reactive graph — manages the element's lifetime
+
+```typescript
+connectedCallback() {
+  // cleanup is tied to disconnectedCallback, not to a reactive owner
+  this.#cleanup = unown(() => createEffect(() => this.render()))
+}
+disconnectedCallback() {
+  this.#cleanup?.()
+}
+```
+</core_functions>
+
+<options>
+**`equals`**
+- Available on `createState`, `createSensor`, `createMemo`, `createTask`
+- Default: strict equality (`===`)
+- When a new value is considered equal to the previous one, propagation stops —
+  downstream nodes are not re-run
+- **`SKIP_EQUALITY`** — special sentinel value for `equals`; forces propagation on every
+  update regardless of value. Use with mutable-reference sensors where the object
+  reference never changes but the contents do:
+
+```typescript
+import { createSensor, SKIP_EQUALITY } from '@zeix/cause-effect'
+
+const mouse = createSensor<{ x: number; y: number }>(
+  set => {
+    const handler = (e: MouseEvent) => set({ x: e.clientX, y: e.clientY })
+    window.addEventListener('mousemove', handler)
+    return () => window.removeEventListener('mousemove', handler)
+  },
+  { equals: SKIP_EQUALITY } // new object every time, so skip reference equality
+)
+```
+
+**`guard`**
+- Available on `createState`, `createSensor`
+- A predicate `(value: unknown) => value is T`
+- Throws `InvalidSignalValueError` if a set value fails the predicate
+- Use to enforce runtime type safety at signal boundaries
+
+```typescript
+const age = createState(0, {
+  guard: (v): v is number => typeof v === 'number' && v >= 0,
+})
+```
+</options>
+
+<callback_patterns>
+**Memo and Task callbacks receive `prev`**
+- Signature: `(prev: T) => T` for Memo; `(prev: T, signal: AbortSignal) => Promise<T>` for Task
+- `prev` is the previous computed value, enabling reducer-style patterns without external state:
+
+```typescript
+const runningTotal = createMemo((prev: number) => prev + newValue.get())
+```
+
+**Task carries an `AbortSignal`**
+- The second argument to the Task callback is an `AbortSignal`
+- The signal is aborted when dependencies change before the previous async run completes
+- Always forward it to any `fetch` or cancellable async operation:
+
+```typescript
+const results = createTask(async (prev, signal) => {
+  const res = await fetch(`/api/search?q=${query.get()}`, { signal })
+  return res.json()
+})
+```
+
+**`Slot` is a property descriptor**
+- Has `get`, `set`, `configurable`, `enumerable` fields
+- Can be passed directly to `Object.defineProperty()`:
+
+```typescript
+const nameSlot = createSlot(store, 'name')
+Object.defineProperty(element, 'name', nameSlot)
+```
+</callback_patterns>
+
+<match_helper>
+`match` reads one or more Sensor/Task signals and routes to `ok` or `nil` based on whether
+all signals have a value. Use it to safely handle the unset state without try/catch:
+
+```typescript
+import { match } from '@zeix/cause-effect'
+
+createEffect(() => {
+  match([task, sensor], {
+    ok:  ([taskResult, sensorValue]) => render(taskResult, sensorValue),
+    nil: () => showSpinner(),
+  })
+})
+```
+
+Read signals you care about eagerly inside `match`'s array — not inside individual branches.
+See `non-obvious-behaviors.md → conditional-reads-delay-watched` for why.
+</match_helper>
+
+<lifecycle_summary>
+| Function | Requires owner? | Returns | Reactive? |
+|---|---|---|---|
+| `createScope(fn)` | No | `Cleanup` | No (fn runs once) |
+| `createEffect(fn)` | **Yes** | `Cleanup` | Yes — re-runs on dependency change |
+| `createMemo(fn)` | No | `Memo<T>` | Lazy — recomputes on read if stale |
+| `createTask(fn)` | No | `Task<T>` | Yes — re-runs async on dependency change |
+| `createState(value)` | No | `State<T>` | Source — never recomputes |
+| `createSensor(setup)` | No | `Sensor<T>` | Source — set by external callback |
+</lifecycle_summary>

package/skills/cause-effect/references/error-classes.md

@@ -0,0 +1,153 @@
+<overview>
+Error classes thrown by @zeix/cause-effect and the conditions that trigger them. All knowledge
+is self-contained — no library source files required. Read this when writing error-handling
+code, testing error conditions, or diagnosing an unexpected throw.
+</overview>
+
+<import>
+All error classes are exported from the package root:
+
+```typescript
+import {
+  NullishSignalValueError,
+  InvalidSignalValueError,
+  InvalidCallbackError,
+  DuplicateKeyError,
+  UnsetSignalValueError,
+  ReadonlySignalError,
+  RequiredOwnerError,
+  CircularDependencyError,
+} from '@zeix/cause-effect'
+```
+</import>
+
+<error_table>
+| Class | When thrown |
+|---|---|
+| `NullishSignalValueError` | Signal value is `null` or `undefined` |
+| `InvalidSignalValueError` | Value fails the `guard` predicate |
+| `InvalidCallbackError` | A required callback argument is not a function |
+| `DuplicateKeyError` | List/Collection key collision on insert |
+| `UnsetSignalValueError` | Reading a Sensor or Task before it has produced its first value |
+| `ReadonlySignalError` | Attempting to write to a read-only signal |
+| `RequiredOwnerError` | `createEffect` called outside an owner (scope or parent effect) |
+| `CircularDependencyError` | A cycle is detected in the reactive graph |
+</error_table>
+
+<error_details>
+
+<NullishSignalValueError>
+Thrown when a signal's value is `null` or `undefined`. Because all signal generics use
+`T extends {}`, nullish values are excluded by design — this error surfaces the constraint
+at runtime if type safety is bypassed (e.g. via a type assertion or untyped interop).
+
+**Prevention:** model absence explicitly with a sentinel value or wrapper type instead of `null`.
+</NullishSignalValueError>
+
+<InvalidSignalValueError>
+Thrown when a value passed to `.set()` fails the `guard` predicate supplied in the signal's
+options. This is the runtime enforcement of custom type narrowing at signal boundaries.
+
+```typescript
+import { createState, InvalidSignalValueError } from '@zeix/cause-effect'
+
+const age = createState(0, {
+  guard: (v): v is number => typeof v === 'number' && v >= 0,
+})
+
+age.set(-1) // throws InvalidSignalValueError
+```
+</InvalidSignalValueError>
+
+<InvalidCallbackError>
+Thrown when a required callback argument — such as the computation function passed to
+`createMemo`, `createTask`, or `createEffect` — is not a function. Catches programming
+errors like passing `undefined` or a non-function value by mistake.
+</InvalidCallbackError>
+
+<DuplicateKeyError>
+Thrown when inserting an item into a List or Collection whose key already exists. Keys must
+be unique within a given List or Collection.
+
+**Fix:** use the collection's update or set method to change an existing entry rather than
+inserting a new one with the same key.
+</DuplicateKeyError>
+
+<UnsetSignalValueError>
+Thrown when `.get()` is called on a Sensor or Task before it has emitted its first value.
+Unlike State, Sensor and Task start in an explicitly unset state with no initial value.
+
+**Fix:** use `match` to handle the unset state (`nil` branch) instead of calling `.get()`
+directly:
+
+```typescript
+import { match } from '@zeix/cause-effect'
+
+createEffect(() => {
+  match([sensor, task], {
+    ok:  ([s, t]) => render(s, t),
+    nil: () => showSpinner(),
+  })
+})
+```
+</UnsetSignalValueError>
+
+<ReadonlySignalError>
+Thrown when code attempts to call `.set()` on a read-only signal. Derived signals (Memo,
+Task) are inherently read-only. Certain factory options may also produce read-only State
+or Sensor instances.
+
+**Fix:** only write to signals you own (State, Sensor via the internal setter callback).
+</ReadonlySignalError>
+
+<RequiredOwnerError>
+Thrown when `createEffect` is called without an active owner in the current execution context.
+Effects must be created inside a `createScope` callback or inside another `createEffect`
+callback so their cleanup can be registered and managed.
+
+```typescript
+import { createEffect, createScope } from '@zeix/cause-effect'
+
+// Wrong — no active owner
+createEffect(() => console.log('runs'))  // throws RequiredOwnerError
+
+// Correct — wrapped in a scope
+const dispose = createScope(() => {
+  createEffect(() => console.log('runs'))
+})
+```
+
+**Exception:** use `unown` when the DOM manages the element's lifetime (e.g. inside
+`connectedCallback`/`disconnectedCallback`) and you intentionally want to bypass owner
+registration.
+</RequiredOwnerError>
+
+<CircularDependencyError>
+Thrown when the graph engine detects a cycle during propagation — a signal that, directly
+or transitively, depends on itself. Cycles make it impossible to determine a stable
+evaluation order and are always a programming error.
+
+**Common causes:**
+- A Memo or Task that writes to a State it also reads
+- Two Memos that read each other
+
+**Fix:** restructure the data flow so that values move in one direction only.
+</CircularDependencyError>
+
+</error_details>
+
+<testing_error_conditions>
+Use `expect(() => ...).toThrow(ErrorClass)` to assert that a specific error is thrown.
+Import the error class from the package root:
+
+```typescript
+import { createState, InvalidSignalValueError } from '@zeix/cause-effect'
+
+test('rejects negative age', () => {
+  const age = createState(0, {
+    guard: (v): v is number => typeof v === 'number' && v >= 0,
+  })
+  expect(() => age.set(-1)).toThrow(InvalidSignalValueError)
+})
+```
+</testing_error_conditions>