@fumari/stf 0.0.3 → 1.0.1

package/dist/index.d.ts

@@ -19,7 +19,7 @@ declare function useStf(options: {
    */
   defaultValues?: DefaultValue<Record<string, unknown>>;
 }): Stf;
-declare function useDataEngine(stf?: Stf): DataEngine;
+declare function useDataEngine(instance?: Stf | DataEngine): DataEngine;
 interface ArrayItemInfo {
   field: FieldKey;
   index: number;
@@ -62,27 +62,43 @@ interface DataEngineListener {
    */
   field?: FieldKey;
   /**
-   * when field value is changed
+   * when field value is changed.
    */
   onUpdate?: (key: FieldKey, ctx: OnUpdateContext) => void;
   /**
-   * when `init(field)` is called
+   * fired on `init(field)`.
    */
-  onInit?: (key: FieldKey) => void;
+  onInit?: (key: FieldKey, ctx: OnInitContext) => void;
   /**
-   * when `delete(field)` is called
+   * fired on `delete(field)`.
+   *
+   * when `field` is specified, this is also fired when parent is deleted.
+   */
+  onDelete?: (key: FieldKey, ctx: OnDeleteContext) => void;
+  /**
+   * For listener attached to a namespace's engine, this is fired when the namespace is removed.
    */
-  onDelete?: (key: FieldKey) => void;
+  onUnmount?: () => void;
 }
 interface OnUpdateContext {
   /**
    * An update is swallow if the change doesn't affect the values of children fields.
    */
   swallow: boolean;
+  /** custom data */
+  custom?: Record<string, unknown>;
+}
+interface OnDeleteContext {
+  /** custom data */
+  custom?: Record<string, unknown>;
+}
+interface OnInitContext {
+  /** custom data */
+  custom?: Record<string, unknown>;
 }
 declare class DataEngine {
   private data;
-  private attachedDataMap;
+  private readonly namespaces;
   private readonly listeners;
   constructor(defaultValues?: DefaultValue<NonNullable<object>>);
   listen(listener: DataEngineListener): void;
@@ -94,23 +110,23 @@ declare class DataEngine {
    * @param defaultValue the initial value, the field is also created for `undefined`
    * @returns the value of initialized field, or the current value of field if already initialized
    */
-  init(key: FieldKey, defaultValue?: DefaultValue): unknown;
-  delete(key: FieldKey): unknown | undefined;
+  init(key: FieldKey, defaultValue?: DefaultValue, ctx?: OnInitContext): unknown;
+  delete(key: FieldKey, ctx?: OnDeleteContext): unknown | undefined;
   get(key: FieldKey): unknown;
   /**
    * update the value of field if it exists
    * @returns if the field is updated
    */
-  update(key: FieldKey, value: unknown): boolean;
-  attachedData<T>(namespace: string): {
-    get: (field: FieldKey) => T | undefined;
-    set: (field: FieldKey, value: T) => void;
-    delete: (field?: FieldKey) => void;
-  };
-  reset(data: Record<string, unknown>): void;
+  update(key: FieldKey, value: unknown, ctx?: Partial<OnUpdateContext>): boolean;
+  /**
+   * create an isolated data engine
+   */
+  namespace(namespace: string, initialValue?: DefaultValue<NonNullable<object>>): DataEngine;
+  reset(data: NonNullable<object>): void;
+  clearNamespaces(): void;
 }
 declare function useFieldValue<V = unknown>(key: FieldKey, options?: {
-  stf?: Stf;
+  stf?: Stf | DataEngine;
   defaultValue?: DefaultValue;
   /**
    * compute value from the actual field value.
@@ -121,7 +137,12 @@ declare function useFieldValue<V = unknown>(key: FieldKey, options?: {
   isChanged?: (prev: V, next: V) => boolean;
 }): readonly [V, (newValue: unknown) => boolean];
 declare function useListener(listener: DataEngineListener & {
-  stf?: Stf;
+  stf?: Stf | DataEngine;
 }): void;
+declare function useNamespace(options: {
+  namespace: string;
+  initial?: DefaultValue<NonNullable<object>>;
+  stf?: Stf | DataEngine;
+}): DataEngine;
 //#endregion
-export { ArrayItemInfo, DataEngine, DataEngineListener, DefaultValue, FieldKey, PropertyItemInfo, Stf, StfProvider, useArray, useDataEngine, useFieldValue, useListener, useObject, useStf };
+export { ArrayItemInfo, DataEngine, DataEngineListener, DefaultValue, FieldKey, OnDeleteContext, OnInitContext, OnUpdateContext, PropertyItemInfo, Stf, StfProvider, useArray, useDataEngine, useFieldValue, useListener, useNamespace, useObject, useStf };

package/dist/index.js

@@ -1,6 +1,6 @@
 'use client';
 
-import { deepEqual, objectGet, objectSet, stringifyFieldKey } from "./lib/utils.js";
+import { deepEqual, fieldKeyStartsWith, isPlainObject, objectGet, objectSet, stringifyFieldKey } from "./lib/utils.js";
 import { createContext, use, useEffect, useMemo, useRef, useState } from "react";
 import { jsx } from "react/jsx-runtime";
 
@@ -17,8 +17,9 @@ function useStf(options) {
 	const dataEngine = useMemo(() => new DataEngine(defaultValues), []);
 	return useMemo(() => ({ dataEngine }), [dataEngine]);
 }
-function useDataEngine(stf) {
-	if (stf) return stf.dataEngine;
+function useDataEngine(instance) {
+	if (instance instanceof DataEngine) return instance;
+	if (instance) return instance.dataEngine;
 	return use(Context).dataEngine;
 }
 function useArray(field, options = {}) {
@@ -142,24 +143,31 @@ var ListenerManager = class {
 			const set = this.indexed.get(updatedKey);
 			if (set) for (const v of set) v.onUpdate?.(field, ctx);
 		} else for (const [k, listeners] of this.indexed.entries()) {
-			if (updatedKey.length !== 0 && k !== updatedKey && !k.startsWith(updatedKey + ".")) continue;
+			if (!fieldKeyStartsWith(k, updatedKey)) continue;
 			for (const v of listeners) v.onUpdate?.(field, ctx);
 		}
 	}
-	onInit(field) {
-		for (const v of this.unindexed) v.onInit?.(field);
+	onInit(field, ctx) {
+		for (const v of this.unindexed) v.onInit?.(field, ctx);
 		const set = this.indexed.get(stringifyFieldKey(field));
-		if (set) for (const v of set) v.onInit?.(field);
+		if (set) for (const v of set) v.onInit?.(field, ctx);
 	}
-	onDelete(field) {
-		for (const v of this.unindexed) v.onDelete?.(field);
-		const set = this.indexed.get(stringifyFieldKey(field));
-		if (set) for (const v of set) v.onDelete?.(field);
+	onDelete(field, ctx) {
+		const fieldKey = stringifyFieldKey(field);
+		for (const v of this.unindexed) v.onDelete?.(field, ctx);
+		for (const [k, listeners] of this.indexed.entries()) {
+			if (!fieldKeyStartsWith(k, fieldKey)) continue;
+			for (const v of listeners) v.onDelete?.(field, ctx);
+		}
+	}
+	onUnmount() {
+		for (const v of this.unindexed) v.onUnmount?.();
+		for (const listeners of this.indexed.values()) for (const v of listeners) v.onUnmount?.();
 	}
 };
-var DataEngine = class {
+var DataEngine = class DataEngine {
 	constructor(defaultValues = {}) {
-		this.attachedDataMap = /* @__PURE__ */ new Map();
+		this.namespaces = /* @__PURE__ */ new Map();
 		this.listeners = new ListenerManager();
 		this.data = getDefaultValue(defaultValues);
 	}
@@ -178,43 +186,59 @@ var DataEngine = class {
 	* @param defaultValue the initial value, the field is also created for `undefined`
 	* @returns the value of initialized field, or the current value of field if already initialized
 	*/
-	init(key, defaultValue) {
+	init(key, defaultValue, ctx = {}) {
 		if (key.length === 0) return this.data;
+		const parentKey = [];
+		const parentUpdateCtx = {
+			swallow: true,
+			...ctx
+		};
 		let cur = this.data;
-		const currentKey = [];
 		for (let i = 0; i < key.length; i++) {
 			const propKey = key[i];
 			const propValue = cur[propKey];
 			if (i === key.length - 1) {
 				if (propValue !== void 0) return propValue;
 				cur[propKey] = getDefaultValue(defaultValue);
-				this.listeners.onUpdate(currentKey, { swallow: true });
-				this.listeners.onInit(key);
+				this.listeners.onUpdate(parentKey, parentUpdateCtx);
+				this.listeners.onInit(key, ctx);
 				return cur[propKey];
-			} else if (typeof propValue === "object" && propValue !== null) cur = propValue;
-			else {
-				if (propValue !== void 0) console.warn(`the original value of field ${currentKey.join(".")} is overidden, this might be unexpected.`);
+			} else if (isPlainObject(propValue)) {
+				cur = propValue;
+				parentKey.push(propKey);
+			} else {
 				cur = cur[propKey] = {};
-				this.listeners.onUpdate(currentKey, { swallow: true });
+				this.listeners.onUpdate(parentKey, parentUpdateCtx);
+				parentKey.push(propKey);
+				if (propValue !== void 0) {
+					console.warn(`the original value of field ${parentKey.join(".")} is overidden, this might be unexpected.`);
+					this.listeners.onUpdate(parentKey, parentUpdateCtx);
+				}
 			}
-			currentKey.push(propKey);
 		}
 	}
-	delete(key) {
+	delete(key, ctx = {}) {
 		if (key.length === 0) return;
 		const parentKey = key.slice(0, -1);
 		const prop = key[key.length - 1];
 		const parent = this.get(parentKey);
 		if (Array.isArray(parent) && typeof prop === "number") {
-			const [deleted] = parent.splice(prop, 1);
-			this.listeners.onUpdate(parentKey, { swallow: false });
-			this.listeners.onDelete(key);
-			return deleted;
-		} else if (typeof parent === "object" && parent !== null) {
+			const deleted = parent.splice(prop, 1);
+			if (deleted.length === 0) return;
+			this.listeners.onDelete(key, ctx);
+			this.listeners.onUpdate(parentKey, {
+				swallow: false,
+				...ctx
+			});
+			return deleted[0];
+		} else if (isPlainObject(parent)) {
 			const temp = parent[prop];
 			delete parent[prop];
-			this.listeners.onUpdate(parentKey, { swallow: true });
-			this.listeners.onDelete(key);
+			this.listeners.onDelete(key, ctx);
+			this.listeners.onUpdate(parentKey, {
+				swallow: true,
+				...ctx
+			});
 			return temp;
 		}
 	}
@@ -225,47 +249,62 @@ var DataEngine = class {
 	* update the value of field if it exists
 	* @returns if the field is updated
 	*/
-	update(key, value) {
+	update(key, value, ctx) {
 		try {
 			this.data = objectSet(this.data, key, value);
-			this.listeners.onUpdate(key, { swallow: false });
+			this.listeners.onUpdate(key, {
+				swallow: false,
+				...ctx
+			});
 			return true;
 		} catch {
 			return false;
 		}
 	}
-	attachedData(namespace) {
-		return {
-			get: (field) => {
-				return this.attachedDataMap.get(`${namespace}:${stringifyFieldKey(field)}`);
-			},
-			set: (field, value) => {
-				this.attachedDataMap.set(`${namespace}:${stringifyFieldKey(field)}`, value);
-			},
-			delete: (field) => {
-				if (field) this.attachedDataMap.delete(`${namespace}:${stringifyFieldKey(field)}`);
-				else for (const key of this.attachedDataMap.keys()) if (key.startsWith(`${namespace}:`)) this.attachedDataMap.delete(key);
-			}
-		};
+	/**
+	* create an isolated data engine
+	*/
+	namespace(namespace, initialValue) {
+		let child = this.namespaces.get(namespace);
+		if (!child) {
+			child = new DataEngine(initialValue);
+			this.namespaces.set(namespace, child);
+		}
+		return child;
 	}
 	reset(data) {
-		this.attachedDataMap.clear();
 		this.update([], data);
 	}
+	clearNamespaces() {
+		for (const [name, engine] of this.namespaces) {
+			this.namespaces.delete(name);
+			engine.listeners.onUnmount();
+		}
+	}
 };
 function useFieldValue(key, options = {}) {
-	const engine = useDataEngine(options.stf);
-	const { compute = (v) => v, defaultValue, isChanged = (a, b) => a !== b } = options;
+	const { stf, compute = (v) => v, defaultValue, isChanged = (a, b) => a !== b } = options;
+	const engine = useDataEngine(stf);
 	const [value, setValue] = useState(() => compute(engine.init(key, defaultValue)));
+	const prevEngineRef = useRef(engine);
+	if (prevEngineRef.current !== engine) {
+		setValue(compute(engine.init(key, defaultValue)));
+		prevEngineRef.current = engine;
+	}
 	useListener({
 		field: key,
+		stf,
+		onInit() {
+			const computed = compute(engine.get(key));
+			setValue((prev) => isChanged(prev, computed) ? computed : prev);
+		},
 		onUpdate() {
 			const computed = compute(engine.get(key));
-			if (isChanged(value, computed)) setValue(computed);
+			setValue((prev) => isChanged(prev, computed) ? computed : prev);
 		},
 		onDelete() {
 			const computed = compute(void 0);
-			if (isChanged(value, computed)) setValue(computed);
+			setValue((prev) => isChanged(prev, computed) ? computed : prev);
 		}
 	});
 	return [value, (newValue) => engine.update(key, newValue)];
@@ -277,6 +316,9 @@ function useListener(listener) {
 	useEffect(() => {
 		const internal = {
 			field: listener.field,
+			onUnmount(...args) {
+				return listenerRef.current.onUnmount?.(...args);
+			},
 			onDelete(...args) {
 				return listenerRef.current.onDelete?.(...args);
 			},
@@ -293,6 +335,18 @@ function useListener(listener) {
 		};
 	}, [engine, listener.field]);
 }
+function useNamespace(options) {
+	const { namespace, stf, initial } = options;
+	const engine = useDataEngine(stf);
+	const [value, setValue] = useState(() => engine.namespace(namespace, initial));
+	useListener({
+		stf: value,
+		onUnmount() {
+			setValue(engine.namespace(namespace, initial));
+		}
+	});
+	return value;
+}
 
 //#endregion
-export { DataEngine, StfProvider, useArray, useDataEngine, useFieldValue, useListener, useObject, useStf };
+export { DataEngine, StfProvider, useArray, useDataEngine, useFieldValue, useListener, useNamespace, useObject, useStf };

package/dist/lib/utils.d.ts

@@ -1,10 +1,6 @@
 import { t as FieldKey } from "../types-Do_aTV5I.js";
 
 //#region src/lib/utils.d.ts
-/**
- * test if array a starts with array b, only compare values via `===`.
- */
-declare function arrayStartsWith(a: unknown[], b: unknown[]): boolean;
 declare function objectGet(obj: unknown, key: (string | number)[]): unknown | undefined;
 /**
  * set the value of field if it exists (in place)
@@ -17,5 +13,10 @@ declare function objectSet(obj: unknown, key: FieldKey, value: unknown): unknown
  */
 declare function deepEqual(a: unknown, b: unknown): boolean;
 declare function stringifyFieldKey(fieldKey: FieldKey): string;
+/**
+ * @returns if `a` starts with `b`.
+ */
+declare function fieldKeyStartsWith(a: string, b: string): boolean;
+declare function isPlainObject(value: unknown): value is Record<string, unknown>;
 //#endregion
-export { arrayStartsWith, deepEqual, objectGet, objectSet, stringifyFieldKey };
+export { deepEqual, fieldKeyStartsWith, isPlainObject, objectGet, objectSet, stringifyFieldKey };

package/dist/lib/utils.js

@@ -1,16 +1,8 @@
 //#region src/lib/utils.ts
-/**
-* test if array a starts with array b, only compare values via `===`.
-*/
-function arrayStartsWith(a, b) {
-	if (b.length > a.length) return false;
-	for (let i = 0; i < b.length; i++) if (a[i] !== b[i]) return false;
-	return true;
-}
 function objectGet(obj, key) {
 	let cur = obj;
 	for (const prop of key) {
-		if (typeof cur !== "object" || cur === null || !(prop in cur)) return;
+		if (!isPlainObject(cur) || !(prop in cur)) return;
 		cur = cur[prop];
 	}
 	return cur;
@@ -23,7 +15,7 @@ function objectGet(obj, key) {
 function objectSet(obj, key, value) {
 	if (key.length === 0) return value;
 	const parent = objectGet(obj, key.slice(0, -1));
-	if (typeof parent !== "object" || parent === null) throw new Error("missing parent object");
+	if (!isPlainObject(parent)) throw new Error("missing parent object");
 	parent[key[key.length - 1]] = value;
 	return obj;
 }
@@ -39,14 +31,26 @@ function deepEqual(a, b) {
 		return a.every((item, index) => deepEqual(item, b[index]));
 	}
 	if (Array.isArray(a) || Array.isArray(b)) return false;
+	if (!isPlainObject(a) || !isPlainObject(b)) return false;
 	const keysA = Object.keys(a);
 	const keysB = Object.keys(b);
 	if (keysA.length !== keysB.length) return false;
-	return keysA.every((key) => Object.prototype.hasOwnProperty.call(b, key) && deepEqual(a[key], b[key]));
+	return keysA.every((key) => key in b && deepEqual(a[key], b[key]));
 }
 function stringifyFieldKey(fieldKey) {
-	return fieldKey.map((v) => `${typeof v}:${v}`).join(".");
+	return fieldKey.map((v) => typeof v === "string" ? `_${v}` : `n${v}`).join(".");
+}
+/**
+* @returns if `a` starts with `b`.
+*/
+function fieldKeyStartsWith(a, b) {
+	return b.length === 0 || a === b || a.startsWith(b + ".");
+}
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === null || prototype === Object.prototype || Object.getPrototypeOf(prototype) === null;
 }
 
 //#endregion
-export { arrayStartsWith, deepEqual, objectGet, objectSet, stringifyFieldKey };
+export { deepEqual, fieldKeyStartsWith, isPlainObject, objectGet, objectSet, stringifyFieldKey };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fumari/stf",
-  "version": "0.0.3",
+  "version": "1.0.1",
   "description": "Schema to Form.",
   "keywords": [],
   "license": "MIT",
@@ -19,8 +19,8 @@
     "access": "public"
   },
   "devDependencies": {
-    "@types/node": "25.2.1",
-    "@types/react": "^19.2.13",
+    "@types/node": "25.2.3",
+    "@types/react": "^19.2.14",
     "tsdown": "^0.20.3",
     "eslint-config-custom": "0.0.0",
     "tsconfig": "0.0.0"