@fumari/stf 1.0.0 → 1.0.2

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.
@@ -92,10 +41,16 @@ interface OnInitContext {
   /** custom data */
   custom?: Record<string, unknown>;
 }
+interface NamespaceConfig {
+  reset?: (ctx: {
+    engine: DataEngine;
+  }) => void;
+}
 declare class DataEngine {
   private data;
-  /** namespace -> engine */
-  private namespaces;
+  readonly namespaces: Map<string, {
+    engine: DataEngine;
+  } & NamespaceConfig>;
   private readonly listeners;
   constructor(defaultValues?: DefaultValue<NonNullable<object>>);
   listen(listener: DataEngineListener): void;
@@ -103,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;
   /**
@@ -118,9 +73,63 @@ declare class DataEngine {
   /**
    * create an isolated data engine
    */
-  namespace(namespace: string, initialValue?: DefaultValue<NonNullable<object>>): DataEngine;
-  reset(data: Record<string, unknown>): void;
+  namespace(namespace: string, initialValue?: DefaultValue<NonNullable<object>>, config?: NamespaceConfig): DataEngine;
+  reset(data: NonNullable<object>): 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;
@@ -135,5 +144,10 @@ declare function useFieldValue<V = unknown>(key: FieldKey, options?: {
 declare function useListener(listener: DataEngineListener & {
   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, OnDeleteContext, OnInitContext, OnUpdateContext, PropertyItemInfo, Stf, StfProvider, useArray, useDataEngine, useFieldValue, useListener, 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

@@ -1,118 +1,9 @@
 'use client';
 
-import { deepEqual, fieldKeyStartsWith, 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";
 
-//#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;
@@ -178,34 +69,46 @@ 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;
-		let cur = this.data;
-		const currentKey = [];
+	init(field, defaultValue, ctx = {}) {
+		if (field.length === 0) return this.data;
+		const parentKey = [];
 		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, 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, parentUpdateCtx);
+		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 {
+				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.`);
+				}
 			}
-			currentKey.push(propKey);
 		}
 	}
 	delete(key, ctx = {}) {
@@ -213,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 (typeof parent === "object" && parent !== null) {
+		} else if (isPlainObject(parent) && prop in parent) {
 			const temp = parent[prop];
 			delete parent[prop];
 			this.listeners.onDelete(key, ctx);
@@ -255,34 +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.namespaces.clear();
 		this.update([], data);
+		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 engine = useDataEngine(options.stf);
-	const { compute = (v) => v, defaultValue, isChanged = (a, b) => a !== b } = options;
-	const [value, setValue] = useState(() => compute(engine.init(key, defaultValue)));
+	const { stf, compute = (v) => v, defaultValue, isChanged = (a, b) => a !== b } = options;
+	const engine = useDataEngine(stf);
+	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(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: options.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);
-		},
+		stf,
+		onInit: onUpdate,
+		onUpdate,
 		onDelete() {
 			const computed = compute(void 0);
 			setValue((prev) => isChanged(prev, computed) ? computed : prev);
@@ -313,6 +340,12 @@ function useListener(listener) {
 		};
 	}, [engine, listener.field]);
 }
+function useNamespace(options) {
+	const { namespace, stf, initial } = options;
+	return useDataEngine(stf).namespace(namespace, initial, { reset({ engine }) {
+		engine.update([], getDefaultValue(initial));
+	} });
+}
 
 //#endregion
-export { DataEngine, StfProvider, useArray, useDataEngine, useFieldValue, useListener, 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
  */
@@ -17,5 +17,6 @@ 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 { deepEqual, fieldKeyStartsWith, objectGet, objectSet, stringifyFieldKey };
+export { deepEqual, fieldKeyStartsWith, isPlainObject, objectGet, objectSet, stringifyFieldKey };

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 (typeof cur !== "object" || cur === null || !(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 (typeof parent !== "object" || parent === null) 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;
 }
 /**
@@ -31,13 +32,14 @@ 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`.
@@ -45,6 +47,11 @@ function stringifyFieldKey(fieldKey) {
 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 { deepEqual, fieldKeyStartsWith, objectGet, objectSet, stringifyFieldKey };
+export { deepEqual, fieldKeyStartsWith, isPlainObject, objectGet, objectSet, stringifyFieldKey };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fumari/stf",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Schema to Form.",
   "keywords": [],
   "license": "MIT",