@firsthandjs/deep 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Firsthand contributors
+
+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

@@ -0,0 +1,63 @@
+# @firsthandjs/deep
+
+Deep reactivity for Firsthand: a proxy where every property, at any depth, is a
+signal — the shape Vue calls `reactive()`.
+
+**Documentation:** [guide](https://github.com/firsthandjs/firsthand/blob/main/docs/guide/02-reactivity.md#deep-state) · [API reference](https://github.com/firsthandjs/firsthand/blob/main/docs/reference/deep.md) · [all docs](https://github.com/firsthandjs/firsthand/blob/main/docs/README.md)
+
+```
+npm install @firsthandjs/deep
+```
+
+0.72 kB gzip. It depends on `@firsthandjs/core` and changes nothing about
+`signal`.
+
+```ts
+import { effect } from '@firsthandjs/core';
+import { deepSignal } from '@firsthandjs/deep';
+
+const state = deepSignal({ user: { name: 'Ada' }, todos: [] as string[] });
+
+effect(() => console.log(state.user.name)); // subscribes to that property
+state.user.name = 'Grace'; // and only that effect re-runs
+state.todos.push('write the docs'); // arrays too, as one update
+```
+
+## Why it exists
+
+A signal holds one value and notices when that value is **replaced**:
+
+```ts
+const form = signal({ user: { name: 'Ada' } });
+form.value.user.name = 'Grace'; // invisible: the signal holds the same object
+```
+
+Replacing the object is right for small state and tedious for a form, a
+document or a settings tree. `deepSignal` tracks per property instead, so an
+effect that read `state.user.name` ignores a change to `state.user.age`, and a
+write to a property nobody has read costs nothing at all.
+
+## Only objects and arrays
+
+```ts
+deepSignal(new Map()); // compile error
+deepSignal(new Date()); // compile error
+deepSignal(new Point()); // compile error
+```
+
+Those read their own internals through `this`, and inside a proxy `this` is the
+proxy — a proxied `Map` throws on `get`. Keep them in a `signal` and replace
+them on each edit; one held inside deep state still works, it is simply not
+reactive itself.
+
+## The rest of the surface
+
+| Export            | What it does                                       |
+| ----------------- | -------------------------------------------------- |
+| `deepSignal(obj)` | The proxy. Same type in, same type out             |
+| `raw(value)`      | The object behind a proxy, for clones and requests |
+| `isDeep(value)`   | Whether something is a proxy this package made     |
+
+Full rules — `Object.keys`, `in`, `delete`, every array mutator, identity — are
+in the [API reference](https://github.com/firsthandjs/firsthand/blob/main/docs/reference/deep.md),
+and the reasoning is in [ADR-0018](https://github.com/firsthandjs/firsthand/blob/main/docs/adr/0018-deep-reactivity-as-its-own-package.md).

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * What may be made deeply reactive: an object or an array.
+ *
+ * Deliberately not `T extends object`. A function, a `Date`, a `Map`, a
+ * `Promise` and a class instance all satisfy `object`, and proxying them
+ * silently breaks them in ways that only show up at runtime — a `Map` reads its
+ * internal slots through `this`, which a proxy is not. Restricting the type
+ * makes that a compile error instead of a bug.
+ */
+export type Deep = Record<PropertyKey, unknown> | unknown[];
+/**
+ * Makes an object or array deeply reactive.
+ *
+ * Returns a proxy with the same shape as what you passed: read it, write it,
+ * spread it, iterate it. Reads inside an `effect`, a `computed` or a DOM
+ * binding subscribe to exactly the properties they touched; writes notify
+ * exactly those readers.
+ *
+ * Calling it twice with the same object returns the same proxy, and calling it
+ * on a proxy returns that proxy, so identity is stable and `===` means what it
+ * looks like.
+ */
+export declare function deepSignal<T extends Deep>(value: T): T;
+/**
+ * The object a deep proxy wraps, or the value itself if it is not one.
+ *
+ * For handing state to something that must not be tracked — a structured
+ * clone, a `fetch` body, a library that stores what it is given.
+ */
+export declare function raw<T>(value: T): T;
+/** Whether a value is a proxy this package created. */
+export declare function isDeep(value: unknown): boolean;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAkCA;;;;;;;;GAQG;AACH,MAAM,MAAM,IAAI,GAAG,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,GAAG,OAAO,EAAE,CAAC;AAgK5D;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,IAAI,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAStD;AAED;;;;;GAKG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAMlC;AAED,uDAAuD;AACvD,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAI9C"}

package/dist/index.js

@@ -0,0 +1 @@
+import{batch as b,signal as h}from"@firsthandjs/core";var p=Symbol.for("firsthand.deep.raw"),y=new WeakMap,f=new WeakMap,u=Symbol.for("firsthand.deep.keys");function j(n,e){let t=f.get(n);t===void 0&&(t=new Map,f.set(n,t));let o=t.get(e);return o===void 0&&(o=h(0),t.set(e,o)),o}function c(n,e){j(n,e).value}function r(n,e){let t=f.get(n)?.get(e);t!==void 0&&t.value++}function A(n){if(typeof n!="object"||n===null)return!1;if(Array.isArray(n))return!0;let e=Object.getPrototypeOf(n);return e===Object.prototype||e===null}var P=new Set(["push","pop","shift","unshift","splice","sort","reverse","fill","copyWithin"]),m={get(n,e,t){if(e===p)return n;let o=Reflect.get(n,e,t);return typeof e=="symbol"?o:Array.isArray(n)&&typeof o=="function"&&P.has(e)?function(...i){return b(()=>o.apply(t,i))}:(c(n,e),A(o)?R(o):o)},set(n,e,t,o){let s=Array.isArray(n),i=Object.prototype.hasOwnProperty.call(n,e),a=Reflect.get(n,e,o),w=s?n.length:0,l=d(t);return Reflect.set(n,e,l,o)?(i?Object.is(a,l)||r(n,e):(r(n,u),r(n,e)),s&&e!=="length"&&n.length!==w&&r(n,"length"),!0):!1},deleteProperty(n,e){let t=Object.prototype.hasOwnProperty.call(n,e),o=Reflect.deleteProperty(n,e);return o&&t&&(r(n,e),r(n,u)),o},has(n,e){return typeof e!="symbol"&&c(n,e),Reflect.has(n,e)},ownKeys(n){return c(n,Array.isArray(n)?"length":u),Reflect.ownKeys(n)}};function R(n){let e=d(n),t=y.get(e);if(t!==void 0)return t;let o=new Proxy(e,m);return y.set(e,o),o}function d(n){if(typeof n!="object"||n===null)return n;let e=n[p];return e===void 0?n:e}function O(n){return typeof n=="object"&&n!==null&&n[p]!==void 0}export{R as deepSignal,O as isDeep,d as raw};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@firsthandjs/deep",
+  "version": "0.2.0",
+  "description": "Deep reactivity for Firsthand: a proxy where every property, at any depth, is a signal.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@firsthandjs/core": "0.2.0"
+  },
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/firsthandjs/firsthand.git",
+    "directory": "packages/deep"
+  },
+  "bugs": {
+    "url": "https://github.com/firsthandjs/firsthand/issues"
+  },
+  "homepage": "https://github.com/firsthandjs/firsthand#readme",
+  "keywords": [
+    "firsthand",
+    "reactive",
+    "proxy",
+    "deep",
+    "state",
+    "signals"
+  ]
+}