@fumari/stf 1.0.1 → 1.0.3

package/dist/index.d.ts

@@ -2,60 +2,9 @@ import { t as FieldKey } from "./types-Do_aTV5I.js";
 import { ReactNode } from "react";
 import * as react_jsx_runtime0 from "react/jsx-runtime";
 
-//#region src/lib/stf.d.ts
-interface Stf {
-  dataEngine: DataEngine;
-}
-declare function StfProvider({
-  value,
-  children
-}: {
-  value: Stf;
-  children: ReactNode;
-}): react_jsx_runtime0.JSX.Element;
-declare function useStf(options: {
-  /**
-   * Note: the passed object will be modified in place, use `structuredClone()` to keep the original object unchanged.
-   */
-  defaultValues?: DefaultValue<Record<string, unknown>>;
-}): Stf;
-declare function useDataEngine(instance?: Stf | DataEngine): DataEngine;
-interface ArrayItemInfo {
-  field: FieldKey;
-  index: number;
-}
-declare function useArray(field: FieldKey, options?: {
-  defaultValue?: DefaultValue<unknown[]>;
-}): {
-  items: ArrayItemInfo[];
-  insertItem(itemValue?: unknown): void;
-  removeItem(index: number): void;
-};
-type PropertyItemInfo<T> = {
-  kind: 'fixed' | 'fallback';
-  field: FieldKey;
-  key: string;
-  info: T;
-} | {
-  kind: 'pattern';
-  field: FieldKey;
-  key: string;
-  pattern: string;
-  info: T;
-};
-declare function useObject<T>(field: FieldKey, options: {
-  defaultValue?: DefaultValue<object>;
-  properties: Record<string, T>;
-  patternProperties?: Record<string, T>;
-  fallback?: T;
-}): {
-  properties: PropertyItemInfo<T>[];
-  onAppend(name: string, value?: unknown): void;
-  onDelete(name: string): unknown;
-};
-//#endregion
 //#region src/lib/data-engine.d.ts
 type DefaultValue<T = unknown> = T | (() => T);
+declare function getDefaultValue<T>(defaultValue: DefaultValue<T>): T;
 interface DataEngineListener {
   /**
    * when specified, only call the listener for events affecting the specified field.
@@ -75,10 +24,6 @@ interface DataEngineListener {
    * 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.
-   */
-  onUnmount?: () => void;
 }
 interface OnUpdateContext {
   /**
@@ -96,9 +41,16 @@ interface OnInitContext {
   /** custom data */
   custom?: Record<string, unknown>;
 }
+interface NamespaceConfig {
+  reset?: (ctx: {
+    engine: DataEngine;
+  }) => void;
+}
 declare class DataEngine {
   private data;
-  private readonly namespaces;
+  readonly namespaces: Map<string, {
+    engine: DataEngine;
+  } & NamespaceConfig>;
   private readonly listeners;
   constructor(defaultValues?: DefaultValue<NonNullable<object>>);
   listen(listener: DataEngineListener): void;
@@ -106,11 +58,11 @@ declare class DataEngine {
   getData(): object;
   /**
    * init a field
-   * @param key the key of field
+   * @param field the key of field
    * @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, ctx?: OnInitContext): unknown;
+  init(field: FieldKey, defaultValue?: DefaultValue, ctx?: OnInitContext): unknown;
   delete(key: FieldKey, ctx?: OnDeleteContext): unknown | undefined;
   get(key: FieldKey): unknown;
   /**
@@ -121,10 +73,63 @@ declare class DataEngine {
   /**
    * create an isolated data engine
    */
-  namespace(namespace: string, initialValue?: DefaultValue<NonNullable<object>>): DataEngine;
+  namespace(namespace: string, initialValue?: DefaultValue<NonNullable<object>>, config?: NamespaceConfig): DataEngine;
   reset(data: NonNullable<object>): void;
-  clearNamespaces(): void;
 }
+//#endregion
+//#region src/lib/stf.d.ts
+interface Stf {
+  dataEngine: DataEngine;
+}
+declare function StfProvider({
+  value,
+  children
+}: {
+  value: Stf;
+  children: ReactNode;
+}): react_jsx_runtime0.JSX.Element;
+declare function useStf(options: {
+  /**
+   * Note: the passed object will be modified in place, use `structuredClone()` to keep the original object unchanged.
+   */
+  defaultValues?: DefaultValue<Record<string, unknown>>;
+}): Stf;
+declare function useDataEngine(instance?: Stf | DataEngine): DataEngine;
+interface ArrayItemInfo {
+  field: FieldKey;
+  index: number;
+}
+declare function useArray(field: FieldKey, options?: {
+  defaultValue?: DefaultValue<unknown[]>;
+}): {
+  items: ArrayItemInfo[];
+  insertItem(itemValue?: unknown): void;
+  removeItem(index: number): void;
+};
+type PropertyItemInfo<T> = {
+  kind: 'fixed' | 'fallback';
+  field: FieldKey;
+  key: string;
+  info: T;
+} | {
+  kind: 'pattern';
+  field: FieldKey;
+  key: string;
+  pattern: string;
+  info: T;
+};
+declare function useObject<T>(field: FieldKey, options: {
+  defaultValue?: DefaultValue<object>; /** ignore fixed properties unless defined  */
+  lazy?: boolean;
+  properties: Record<string, T>;
+  patternProperties?: Record<string, T>;
+  fallback?: T;
+}): {
+  properties: PropertyItemInfo<T>[];
+  _objectKeys: string[];
+  onAppend(name: string, value?: unknown): void;
+  onDelete(name: string): unknown;
+};
 declare function useFieldValue<V = unknown>(key: FieldKey, options?: {
   stf?: Stf | DataEngine;
   defaultValue?: DefaultValue;
@@ -145,4 +150,4 @@ declare function useNamespace(options: {
   stf?: Stf | DataEngine;
 }): DataEngine;
 //#endregion
-export { ArrayItemInfo, DataEngine, DataEngineListener, DefaultValue, FieldKey, OnDeleteContext, OnInitContext, OnUpdateContext, PropertyItemInfo, Stf, StfProvider, useArray, useDataEngine, useFieldValue, useListener, useNamespace, useObject, useStf };
+export { ArrayItemInfo, DataEngine, DataEngineListener, DefaultValue, FieldKey, NamespaceConfig, OnDeleteContext, OnInitContext, OnUpdateContext, PropertyItemInfo, Stf, StfProvider, getDefaultValue, useArray, useDataEngine, useFieldValue, useListener, useNamespace, useObject, useStf };

package/dist/index.js

@@ -4,115 +4,6 @@ import { deepEqual, fieldKeyStartsWith, isPlainObject, objectGet, objectSet, str
 import { createContext, use, useEffect, useMemo, useRef, useState } from "react";
 import { jsx } from "react/jsx-runtime";
 
-//#region src/lib/stf.tsx
-const Context = createContext(null);
-function StfProvider({ value, children }) {
-	return /* @__PURE__ */ jsx(Context, {
-		value,
-		children
-	});
-}
-function useStf(options) {
-	const { defaultValues } = options;
-	const dataEngine = useMemo(() => new DataEngine(defaultValues), []);
-	return useMemo(() => ({ dataEngine }), [dataEngine]);
-}
-function useDataEngine(instance) {
-	if (instance instanceof DataEngine) return instance;
-	if (instance) return instance.dataEngine;
-	return use(Context).dataEngine;
-}
-function useArray(field, options = {}) {
-	const engine = useDataEngine();
-	const [items] = useFieldValue(field, {
-		defaultValue: options.defaultValue,
-		compute(value) {
-			const items = [];
-			if (Array.isArray(value)) for (let i = 0; i < value.length; i++) items.push({
-				field: [...field, i],
-				index: i
-			});
-			return items;
-		},
-		isChanged(prev, next) {
-			return prev.length !== next.length;
-		}
-	});
-	return {
-		items,
-		insertItem(itemValue) {
-			const value = engine.get(field);
-			engine.update(field, Array.isArray(value) ? [...value, itemValue] : [itemValue]);
-		},
-		removeItem(index) {
-			engine.delete([...field, index]);
-		}
-	};
-}
-function useObject(field, options) {
-	const engine = useDataEngine();
-	const [objectKeys] = useFieldValue(field, {
-		defaultValue: options.defaultValue,
-		compute(currentValue) {
-			return currentValue ? Object.keys(currentValue) : [];
-		},
-		isChanged(prev, next) {
-			return !deepEqual(prev, next);
-		}
-	});
-	return {
-		properties: useMemo(() => {
-			const properties = [];
-			const unknownKeys = new Set(objectKeys);
-			for (const [key, prop] of Object.entries(options.properties)) {
-				unknownKeys.delete(key);
-				properties.push({
-					kind: "fixed",
-					field: [...field, key],
-					key,
-					info: prop
-				});
-			}
-			for (const [pattern, prop] of Object.entries(options.patternProperties ?? {})) {
-				const regex = RegExp(pattern);
-				for (const key of unknownKeys) {
-					if (!key.match(regex)) continue;
-					unknownKeys.delete(key);
-					properties.push({
-						kind: "pattern",
-						info: prop,
-						key,
-						pattern,
-						field: [...field, key]
-					});
-				}
-			}
-			if (options.fallback) for (const key of unknownKeys) properties.push({
-				kind: "fallback",
-				field: [...field, key],
-				key,
-				info: options.fallback
-			});
-			return properties;
-		}, [
-			field,
-			objectKeys,
-			options.fallback,
-			options.patternProperties,
-			options.properties
-		]),
-		onAppend(name, value) {
-			name = name.trim();
-			if (name.length === 0) return;
-			engine.init([...field, name], value);
-		},
-		onDelete(name) {
-			return engine.delete([...field, name]);
-		}
-	};
-}
-
-//#endregion
 //#region src/lib/data-engine.ts
 function getDefaultValue(defaultValue) {
 	return typeof defaultValue === "function" ? defaultValue() : defaultValue;
@@ -160,10 +51,6 @@ var ListenerManager = class {
 			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 DataEngine {
 	constructor(defaultValues = {}) {
@@ -182,37 +69,44 @@ var DataEngine = class DataEngine {
 	}
 	/**
 	* init a field
-	* @param key the key of field
+	* @param field the key of field
 	* @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, ctx = {}) {
-		if (key.length === 0) return this.data;
+	init(field, defaultValue, ctx = {}) {
+		if (field.length === 0) return this.data;
 		const parentKey = [];
 		const parentUpdateCtx = {
 			swallow: true,
 			...ctx
 		};
-		let cur = this.data;
-		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(parentKey, parentUpdateCtx);
-				this.listeners.onInit(key, ctx);
-				return cur[propKey];
-			} else if (isPlainObject(propValue)) {
-				cur = propValue;
-				parentKey.push(propKey);
+		let parent = this.data;
+		const fieldsToInit = [];
+		let initStart = null;
+		for (let i = 0; i < field.length; i++) {
+			const key = field[i];
+			const value = parent[key];
+			if (i === field.length - 1) {
+				if (value !== void 0) return value;
+				const out = parent[key] = getDefaultValue(defaultValue);
+				fieldsToInit.push(field);
+				for (const initField of fieldsToInit) this.listeners.onInit(initField, ctx);
+				this.listeners.onUpdate(initStart ?? parentKey, parentUpdateCtx);
+				return out;
+			} else if (isPlainObject(value) || Array.isArray(value)) {
+				parent = value;
+				parentKey.push(key);
 			} else {
-				cur = cur[propKey] = {};
-				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.`);
+				const nextKey = field[i + 1];
+				parent = parent[key] = typeof nextKey === "number" ? new Array(nextKey + 1) : {};
+				if (value === void 0) {
+					initStart ??= [...parentKey];
+					parentKey.push(key);
+					fieldsToInit.push([...parentKey]);
+				} else {
+					parentKey.push(key);
 					this.listeners.onUpdate(parentKey, parentUpdateCtx);
+					console.warn(`the original value of field ${parentKey.join(".")} is overidden, this might be unexpected.`);
 				}
 			}
 		}
@@ -222,16 +116,18 @@ var DataEngine = class DataEngine {
 		const parentKey = key.slice(0, -1);
 		const prop = key[key.length - 1];
 		const parent = this.get(parentKey);
-		if (Array.isArray(parent) && typeof prop === "number") {
+		if (typeof prop === "number" && Array.isArray(parent)) {
+			if (parent.length === 0) return;
+			const isLast = prop === parent.length - 1;
 			const deleted = parent.splice(prop, 1);
 			if (deleted.length === 0) return;
 			this.listeners.onDelete(key, ctx);
 			this.listeners.onUpdate(parentKey, {
-				swallow: false,
+				swallow: isLast,
 				...ctx
 			});
 			return deleted[0];
-		} else if (isPlainObject(parent)) {
+		} else if (isPlainObject(parent) && prop in parent) {
 			const temp = parent[prop];
 			delete parent[prop];
 			this.listeners.onDelete(key, ctx);
@@ -264,44 +160,156 @@ var DataEngine = class DataEngine {
 	/**
 	* create an isolated data engine
 	*/
-	namespace(namespace, initialValue) {
+	namespace(namespace, initialValue, config) {
 		let child = this.namespaces.get(namespace);
 		if (!child) {
-			child = new DataEngine(initialValue);
+			child = {
+				engine: new DataEngine(initialValue),
+				...config
+			};
 			this.namespaces.set(namespace, child);
-		}
-		return child;
+		} else Object.assign(child, config);
+		return child.engine;
 	}
 	reset(data) {
 		this.update([], data);
-	}
-	clearNamespaces() {
-		for (const [name, engine] of this.namespaces) {
-			this.namespaces.delete(name);
-			engine.listeners.onUnmount();
-		}
+		for (const { engine, reset } of this.namespaces.values()) reset?.({ engine });
 	}
 };
+
+//#endregion
+//#region src/lib/stf.tsx
+const Context = createContext(null);
+function StfProvider({ value, children }) {
+	return /* @__PURE__ */ jsx(Context, {
+		value,
+		children
+	});
+}
+function useStf(options) {
+	const optionsRef = useRef(options);
+	optionsRef.current = options;
+	return useMemo(() => ({ dataEngine: new DataEngine(optionsRef.current.defaultValues) }), []);
+}
+function useDataEngine(instance) {
+	if (instance instanceof DataEngine) return instance;
+	if (instance) return instance.dataEngine;
+	return use(Context).dataEngine;
+}
+function useArray(field, options = {}) {
+	const engine = useDataEngine();
+	const { defaultValue } = options;
+	const [items] = useFieldValue(field, {
+		defaultValue,
+		compute(value) {
+			const items = [];
+			if (!Array.isArray(value)) return items;
+			for (let i = 0; i < value.length; i++) items.push({
+				field: [...field, i],
+				index: i
+			});
+			return items;
+		},
+		isChanged(prev, next) {
+			return prev.length !== next.length;
+		}
+	});
+	return {
+		items,
+		insertItem(itemValue) {
+			const value = engine.get(field);
+			const idx = Array.isArray(value) ? value.length : 0;
+			engine.init([...field, idx], itemValue);
+		},
+		removeItem(index) {
+			engine.delete([...field, index]);
+		}
+	};
+}
+function useObject(field, options) {
+	const { properties: definedProps, patternProperties: definedPatternProps = {}, defaultValue, fallback, lazy } = options;
+	const engine = useDataEngine();
+	const [objectKeys] = useFieldValue(field, {
+		defaultValue,
+		compute(currentValue) {
+			return isPlainObject(currentValue) ? Object.keys(currentValue) : [];
+		},
+		isChanged(prev, next) {
+			return !deepEqual(prev, next);
+		}
+	});
+	return {
+		properties: useMemo(() => {
+			const properties = [];
+			const unknownKeys = new Set(objectKeys);
+			for (const [key, prop] of Object.entries(definedProps)) {
+				if (lazy && !unknownKeys.has(key)) continue;
+				unknownKeys.delete(key);
+				properties.push({
+					kind: "fixed",
+					field: [...field, key],
+					key,
+					info: prop
+				});
+			}
+			for (const [pattern, prop] of Object.entries(definedPatternProps)) {
+				const regex = RegExp(pattern);
+				for (const key of unknownKeys) {
+					if (!key.match(regex)) continue;
+					unknownKeys.delete(key);
+					properties.push({
+						kind: "pattern",
+						info: prop,
+						key,
+						pattern,
+						field: [...field, key]
+					});
+				}
+			}
+			if (fallback) for (const key of unknownKeys) properties.push({
+				kind: "fallback",
+				field: [...field, key],
+				key,
+				info: fallback
+			});
+			return properties;
+		}, [
+			definedPatternProps,
+			definedProps,
+			fallback,
+			field,
+			lazy,
+			objectKeys
+		]),
+		_objectKeys: objectKeys,
+		onAppend(name, value) {
+			name = name.trim();
+			if (name.length === 0) return;
+			engine.init([...field, name], value);
+		},
+		onDelete(name) {
+			return engine.delete([...field, name]);
+		}
+	};
+}
 function useFieldValue(key, 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 [value, setValue] = useState(() => compute(defaultValue === void 0 ? engine.get(key) : engine.init(key, defaultValue)));
 	const prevEngineRef = useRef(engine);
 	if (prevEngineRef.current !== engine) {
-		setValue(compute(engine.init(key, defaultValue)));
+		setValue(compute(defaultValue === void 0 ? engine.get(key) : engine.init(key, defaultValue)));
 		prevEngineRef.current = engine;
 	}
+	function onUpdate() {
+		const computed = compute(engine.get(key));
+		setValue((prev) => isChanged(prev, computed) ? computed : prev);
+	}
 	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));
-			setValue((prev) => isChanged(prev, computed) ? computed : prev);
-		},
+		onInit: onUpdate,
+		onUpdate,
 		onDelete() {
 			const computed = compute(void 0);
 			setValue((prev) => isChanged(prev, computed) ? computed : prev);
@@ -316,9 +324,6 @@ function useListener(listener) {
 	useEffect(() => {
 		const internal = {
 			field: listener.field,
-			onUnmount(...args) {
-				return listenerRef.current.onUnmount?.(...args);
-			},
 			onDelete(...args) {
 				return listenerRef.current.onDelete?.(...args);
 			},
@@ -337,16 +342,10 @@ function useListener(listener) {
 }
 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;
+	return useDataEngine(stf).namespace(namespace, initial, { reset({ engine }) {
+		engine.update([], getDefaultValue(initial));
+	} });
 }
 
 //#endregion
-export { DataEngine, StfProvider, useArray, useDataEngine, useFieldValue, useListener, useNamespace, useObject, useStf };
+export { DataEngine, StfProvider, getDefaultValue, useArray, useDataEngine, useFieldValue, useListener, useNamespace, useObject, useStf };

package/dist/lib/utils.d.ts

@@ -7,7 +7,7 @@ declare function objectGet(obj: unknown, key: (string | number)[]): unknown | un
  *
  * @returns updated value, throw error if parent object doesn't exist
  */
-declare function objectSet(obj: unknown, key: FieldKey, value: unknown): unknown;
+declare function objectSet(obj: unknown, field: FieldKey, value: unknown): unknown;
 /**
  * doesn't handle recursive objects
  */

package/dist/lib/utils.js

@@ -1,10 +1,9 @@
 //#region src/lib/utils.ts
 function objectGet(obj, key) {
 	let cur = obj;
-	for (const prop of key) {
-		if (!isPlainObject(cur) || !(prop in cur)) return;
-		cur = cur[prop];
-	}
+	for (const prop of key) if (isPlainObject(cur) && prop in cur) cur = cur[prop];
+	else if (typeof prop === "number" && Array.isArray(cur)) cur = cur[prop];
+	else return;
 	return cur;
 }
 /**
@@ -12,11 +11,13 @@ function objectGet(obj, key) {
 *
 * @returns updated value, throw error if parent object doesn't exist
 */
-function objectSet(obj, key, value) {
-	if (key.length === 0) return value;
-	const parent = objectGet(obj, key.slice(0, -1));
-	if (!isPlainObject(parent)) throw new Error("missing parent object");
-	parent[key[key.length - 1]] = value;
+function objectSet(obj, field, value) {
+	if (field.length === 0) return value;
+	const parent = objectGet(obj, field.slice(0, -1));
+	const key = field[field.length - 1];
+	if (isPlainObject(parent)) parent[key] = value;
+	else if (typeof key === "number" && Array.isArray(parent)) parent[key] = value;
+	else throw new Error("missing parent object");
 	return obj;
 }
 /**

package/package.json

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