@cplieger/reactive 1.1.0 → 1.2.0

package/LICENSE

@@ -689,4 +689,4 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.
 
 You should have received a copy of the GNU General Public License
-along with this program.  If not, see <https://www.gnu.org/licenses/>.
+along with this program.  If not, see <https://www.gnu.org/licenses/>.

package/README.md

@@ -1,9 +1,10 @@
 # reactive
 
-[![CI](https://github.com/cplieger/reactive/actions/workflows/ci.yaml/badge.svg)](https://github.com/cplieger/reactive/actions/workflows/ci.yaml)
 [![npm](https://img.shields.io/npm/v/@cplieger/reactive)](https://www.npmjs.com/package/@cplieger/reactive)
 [![JSR](https://jsr.io/badges/@cplieger/reactive)](https://jsr.io/@cplieger/reactive)
-[![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](LICENSE)
+[![Test coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/cplieger/reactive/badges/coverage.json)](https://github.com/cplieger/reactive/actions/workflows/coverage.yml)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13218/badge)](https://www.bestpractices.dev/projects/13218)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/cplieger/reactive/badge)](https://scorecard.dev/viewer/?uri=github.com/cplieger/reactive)
 
 > Signals + collections + DOM-reconciliation micro-framework for TypeScript
 
@@ -73,7 +74,7 @@ isComputed(doubled); // true
 - `batch(fn)` — coalesce signal writes; effects flush synchronously at end of outermost batch
 - `flushSync()` — synchronously drain pending effects (no-op inside batch)
 - `untracked<T>(fn): T` — run fn without tracking signal reads (like Preact `untracked()` / Solid `untrack()`)
-- `on(deps, fn, options?): () => U | undefined` — explicit dependency declaration helper (like Solid `on()`). Pass into `effect()` or `computed()`.
+- `on(deps, fn, options?): () => U` — explicit dependency declaration helper (like Solid `on()`). Returns `() => U`; with `{ defer: true }` the accessor returns `() => U | undefined` (the deferred first call yields `undefined`). A single accessor `() => T` types `value`/`prev` as `T`; an array of accessors types them as `unknown[]`. Pass into `effect()` or `computed()`.
 - `subscribe(signal, cb): () => void` — subscribe to a signal, calling cb immediately and on every change
 - `isSignal(value): boolean` — type guard for signals created by `signal()`
 - `isComputed(value): boolean` — type guard for computed signals

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/reactive",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "exports": {
     ".": "./src/index.ts"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/reactive",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -13,14 +13,14 @@
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
-    "@vitest/coverage-v8": "4.1.8",
-    "eslint": "10.4.1",
+    "@vitest/coverage-v8": "4.1.9",
+    "eslint": "10.5.0",
     "fast-check": "4.8.0",
-    "happy-dom": "20.10.2",
-    "prettier": "3.8.3",
+    "happy-dom": "20.10.3",
+    "prettier": "3.8.4",
     "typescript": "6.0.3",
-    "typescript-eslint": "8.60.1",
-    "vitest": "4.1.8"
+    "typescript-eslint": "8.61.1",
+    "vitest": "4.1.9"
   },
   "description": "Signals + DOM-reconciliation reactive core for TypeScript (zero dependencies)",
   "license": "GPL-3.0-or-later",

package/src/signal.ts

@@ -662,7 +662,39 @@ export function isComputed(value: unknown): value is ReadonlySignal<unknown> {
   return value !== null && typeof value === "object" && COMPUTED_BRAND in value;
 }
 
-/** Explicit dependency declaration helper. Mirrors Solid's on(). */
+/** Explicit dependency declaration helper. Mirrors Solid's on().
+ *
+ * Overloaded so the return type and the `value`/`prev` parameter types stay
+ * tight:
+ *   - Without `defer` (or `{ defer: false }`) the accessor always returns `U`;
+ *     only the `{ defer: true | boolean }` form widens to `U | undefined`
+ *     (the deferred first call yields `undefined`).
+ *   - A single accessor `() => T` correlates `value`/`prev` to `T`; an array of
+ *     accessors correlates them to `unknown[]`. */
+// Single accessor, non-deferred (or explicit `{ defer: false }`): never undefined.
+export function on<T, U>(
+  deps: () => T,
+  fn: (value: T, prev: T | undefined, prevResult: U | undefined) => U,
+  options?: { defer?: false },
+): () => U;
+// Single accessor, deferred: first call returns undefined.
+export function on<T, U>(
+  deps: () => T,
+  fn: (value: T, prev: T | undefined, prevResult: U | undefined) => U,
+  options: { defer: boolean },
+): () => U | undefined;
+// Array of accessors, non-deferred (or explicit `{ defer: false }`): never undefined.
+export function on<U>(
+  deps: (() => unknown)[],
+  fn: (value: unknown[], prev: unknown[] | undefined, prevResult: U | undefined) => U,
+  options?: { defer?: false },
+): () => U;
+// Array of accessors, deferred: first call returns undefined.
+export function on<U>(
+  deps: (() => unknown)[],
+  fn: (value: unknown[], prev: unknown[] | undefined, prevResult: U | undefined) => U,
+  options: { defer: boolean },
+): () => U | undefined;
 export function on<T, U>(
   deps: (() => T) | (() => unknown)[],
   fn: (value: T | unknown[], prev: T | unknown[] | undefined, prevResult: U | undefined) => U,