@fumari/stf 0.0.3 → 1.0.0

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,40 @@ 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) => void;
+  onDelete?: (key: FieldKey, ctx: OnDeleteContext) => 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;
+  /** namespace -> engine */
+  private namespaces;
   private readonly listeners;
   constructor(defaultValues?: DefaultValue<NonNullable<object>>);
   listen(listener: DataEngineListener): void;
@@ -94,23 +107,22 @@ 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;
-  };
+  update(key: FieldKey, value: unknown, ctx?: Partial<OnUpdateContext>): boolean;
+  /**
+   * create an isolated data engine
+   */
+  namespace(namespace: string, initialValue?: DefaultValue<NonNullable<object>>): DataEngine;
   reset(data: Record<string, unknown>): 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 +133,7 @@ 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;
 //#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, useObject, useStf };

package/dist/index.js

@@ -1,6 +1,6 @@
 'use client';
 
-import { deepEqual, objectGet, objectSet, stringifyFieldKey } from "./lib/utils.js";
+import { deepEqual, fieldKeyStartsWith, 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,27 @@ 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);
+		}
 	}
 };
-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 +182,54 @@ 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;
 		let cur = this.data;
 		const currentKey = [];
+		const parentUpdateCtx = {
+			swallow: true,
+			...ctx
+		};
 		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(currentKey, 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.`);
 				cur = cur[propKey] = {};
-				this.listeners.onUpdate(currentKey, { swallow: true });
+				this.listeners.onUpdate(currentKey, 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;
+			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 (typeof parent === "object" && parent !== null) {
 			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,31 +240,31 @@ 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.namespaces.clear();
 		this.update([], data);
 	}
 };
@@ -259,13 +274,18 @@ function useFieldValue(key, options = {}) {
 	const [value, setValue] = useState(() => compute(engine.init(key, defaultValue)));
 	useListener({
 		field: key,
+		stf: options.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)];

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,9 @@ 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;
 //#endregion
-export { arrayStartsWith, deepEqual, objectGet, objectSet, stringifyFieldKey };
+export { deepEqual, fieldKeyStartsWith, objectGet, objectSet, stringifyFieldKey };

package/dist/lib/utils.js

@@ -1,12 +1,4 @@
 //#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) {
@@ -47,6 +39,12 @@ function deepEqual(a, b) {
 function stringifyFieldKey(fieldKey) {
 	return fieldKey.map((v) => `${typeof v}:${v}`).join(".");
 }
+/**
+* @returns if `a` starts with `b`.
+*/
+function fieldKeyStartsWith(a, b) {
+	return b.length === 0 || a === b || a.startsWith(b + ".");
+}
 
 //#endregion
-export { arrayStartsWith, deepEqual, objectGet, objectSet, stringifyFieldKey };
+export { deepEqual, fieldKeyStartsWith, objectGet, objectSet, stringifyFieldKey };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fumari/stf",
-  "version": "0.0.3",
+  "version": "1.0.0",
   "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"