refactor(form): refactor core, merge type definitions, optimize validation logic, and remove redundant code

Author: Ohh-889

primitives/filed-form /src/form-core/createStore.ts

@@ -6,9 +6,6 @@
 
 import { assign, isArray, isEqual, isNil, toArray } from 'skyroc-utils';
 
-import type { FieldEntity } from '../types/field';
-import type { Callbacks, Store, StoreValue } from '../types/formStore';
-import type { Meta } from '../types/shared-types';
 import { get } from '../utils/get';
 import { set, unset } from '../utils/set';
 import type { NamePath, PathTuple } from '../utils/util';
@@ -17,7 +14,8 @@ import { anyOn, collectDeepKeys, isOn, isUnderPrefix, keyOfName, microtask } fro
 import { type ChangeMask, ChangeTag } from './event';
 import type { Action, ArrayOpArgs, Middleware, ValidateFieldsOptions } from './middleware';
 import { compose } from './middleware';
-import type { ValidateMessages } from './types';
+import type { Callbacks, FieldEntity, Meta, Store, StoreValue } from './types';
+import type { ValidateMessages } from './validate';
 import { runRulesWithMode } from './validation';
 import type { Rule, ValidateOptions } from './validation';
 
@@ -34,6 +32,9 @@ export type ArrayField = {
   keys: number[];
 };
 
+/**
+ * Checks if a validation rule should be triggered based on the provided trigger
+ */
 const matchTrigger = (rule: Rule, trig?: string | string[]) => {
   const list = toArray(rule.validateTrigger);
 
@@ -44,12 +45,18 @@ const matchTrigger = (rule: Rule, trig?: string | string[]) => {
   return trigList.some(t => list.includes(t));
 };
 
+/**
+ * Extracts values from a Map based on provided field names
+ */
 function getValueByNames<T>(source: Map<string, T>, names?: NamePath[]): Record<string, T> {
   const keys = names?.length ? names.map(keyOfName) : Array.from(source.keys());
 
   return Object.fromEntries(keys.map(k => [k, source.get(k)!]));
 }
 
+/**
+ * Checks if any field in the provided names has a flag set in the bucket
+ */
 function getFlag(bucket: Set<string>, names?: NamePath[]) {
   if (!names || names.length === 0) {
     return bucket.size > 0;
@@ -58,6 +65,9 @@ function getFlag(bucket: Set<string>, names?: NamePath[]) {
   return anyOn(bucket, names);
 }
 
+/**
+ * Moves an array element from one index to another
+ */
 function move<T>(arr: T[], from: number, to: number): T[] {
   const clone = arr.slice();
   const item = clone.splice(from, 1)[0];
@@ -210,9 +220,7 @@ class FormStore {
   private rebindMiddlewares = () => {
     const api = {
       dispatch: (a: Action) => this.dispatch(a),
-      // eslint-disable-next-line sort/object-properties
-      getState: () => this._store,
-      getFields: this.getFields
+      getState: () => this._store
     };
 
     const chain = this._middlewares.map(m => m(api));
@@ -245,11 +253,11 @@ class FormStore {
         this.arrayOp(a.name, a.args);
         break;
       case 'setExternalErrors': {
-        const { entries } = a as any;
+        const { entries } = a;
 
         this.transaction(() => {
           if (entries.length === 0) {
-            // ✅ 空数组代表全通过，清空所有错误
+            // ✅ Empty array means all validation passed, clear all errors
             this._errors.clear();
             this.enqueueNotify(
               Array.from(this._fieldEntities, e => e.name as string),
@@ -983,6 +991,9 @@ class FormStore {
 
   // ===== Array Operation =====
 
+  /**
+   * Gets or creates an array key manager for tracking array field keys
+   */
   private getArrayKeyManager = (name: string) => {
     let mgr = this.arrayKeyMap.get(name);
     if (!mgr) {
@@ -992,6 +1003,9 @@ class FormStore {
     return mgr;
   };
 
+  /**
+   * Performs array operations on form fields (insert, remove, move, swap, replace)
+   */
   private arrayOp(name: NamePath, args: ArrayOpArgs): void {
     const arr = this.getFieldValue(name);
     if (!Array.isArray(arr)) return;
@@ -1077,6 +1091,10 @@ class FormStore {
   };
 
   // ===== FieldChange =====
+  /**
+   * Triggers the onFieldsChange callback for specified fields
+   * @param nameList - Array of field names that have changed
+   */
   triggerOnFieldsChange = (nameList: NamePath[]) => {
     if (this._callbacks?.onFieldsChange) {
       const fields = this.getFields();
@@ -1091,10 +1109,16 @@ class FormStore {
 
   // ===== Submit =====
 
+  /**
+   * Registers a pre-submit transform function
+   */
   usePreSubmit(fn: (values: Store) => Store) {
     this._preSubmit.push(fn);
   }
 
+  /**
+   * Removes disabled and hidden fields from values before submission
+   */
   private _pruneForSubmit(values: Store): Store {
     const disabled = Array.from(this._disabledKeys);
     const hidden = Array.from(this._hiddenKeys);
@@ -1119,6 +1143,10 @@ class FormStore {
     return walk(values, []) ?? {};
   }
 
+  /**
+   * Builds the payload for failed form submission
+   * @returns Object containing error information and form state
+   */
   private buildFailedPayload = () => {
     const errorMap = Object.fromEntries(this._errors);
     const warningMap = Object.fromEntries(this._warnings);
@@ -1148,13 +1176,20 @@ class FormStore {
     };
   };
 
+  /**
+   * Submits the form after validation
+   * Calls onFinish if validation passes, onFinishFailed if it fails
+   */
   private submit = () => {
     this.validateFields().then(ok => {
       if (ok) this._callbacks.onFinish?.(this._store);
       else this._callbacks.onFinishFailed?.(this.buildFailedPayload());
     });
   };
 
+  /**
+   * Destroys the form and cleans up all state
+   */
   private destroyForm = (clearOnDestroy?: boolean) => {
     if (clearOnDestroy) {
       // destroy form reset store

primitives/filed-form /src/form-core/event.ts

@@ -1,40 +1,95 @@
 /* eslint-disable @typescript-eslint/prefer-literal-enum-member */
 /* eslint-disable no-bitwise */
 
+/**
+ * Form field change event system
+ * Uses bitwise flags to efficiently track and combine different types of field changes
+ */
+
+/**
+ * Enumeration of change tags using bitwise flags
+ * Each tag represents a different type of field change that can be tracked
+ */
 export enum ChangeTag {
+  /** Field value has changed */
   Value = 0b000001,
+  /** Field is currently being validated */
   Validating = 0b000010,
+  /** Field validation errors have changed */
   Errors = 0b000100,
+  /** Field validation warnings have changed */
   Warnings = 0b001000,
+  /** Field has been touched by user interaction */
   Touched = 0b010000,
+  /** Field value differs from initial value */
   Dirty = 0b100000,
+  /** Field validation has completed */
   Validated = 0b1000000,
+  /** Field has been reset */
   Reset = 0b10000000,
+  /** Combination of all validation status flags */
   Status = Errors | Warnings | Validated | Validating,
+  /** All possible change flags */
   All = 0x7fffffff
 }
 
+/**
+ * Type representing a bitmask of change flags
+ * Used to efficiently combine and check multiple change types
+ */
 export type ChangeMask = number;
 
+/**
+ * Checks if a change mask contains a specific tag
+ * @param mask - The change mask to check
+ * @param tag - The tag to look for
+ * @returns True if the mask contains the tag
+ */
 export const hasTag = (mask: ChangeMask, tag: ChangeTag) => (mask & tag) !== 0;
+
+/**
+ * Adds one or more tags to a change mask
+ */
 export const addTag = (mask: ChangeMask, ...tags: ChangeTag[]) => tags.reduce((m, t) => m | t, mask);
+
+/**
+ * Removes one or more tags from a change mask
+ */
 export const delTag = (mask: ChangeMask, ...tags: ChangeTag[]) => tags.reduce((m, t) => m & ~t, mask);
 
+/**
+ * Options for configuring subscription masks
+ * Used to specify which types of changes to listen for
+ */
 export interface SubscribeMaskOptions {
+  /** Subscribe to all change types */
   all?: boolean;
+  /** Subscribe to dirty state changes */
   dirty?: boolean;
+  /** Subscribe to validation error changes */
   errors?: boolean;
+  /** Subscribe to field reset events */
   reset?: boolean;
+  /** Subscribe to touched state changes */
   touched?: boolean;
+  /** Subscribe to validation completion events */
   validated?: boolean;
+  /** Subscribe to validation status changes */
   validating?: boolean;
+  /** Subscribe to value changes */
   value?: boolean;
+  /** Subscribe to validation warning changes */
   warnings?: boolean;
 }
 
+/**
+ * Converts subscription options to a change mask
+ */
 export const toMask = (opt: SubscribeMaskOptions = {}): ChangeMask => {
+  // If 'all' is specified, return mask for all changes
   if (opt.all) return ChangeTag.All;
 
+  // Build array of selected tags
   const tags: ChangeTag[] = [];
   if (opt.value) tags.push(ChangeTag.Value);
   if (opt.errors) tags.push(ChangeTag.Errors);
@@ -45,5 +100,6 @@ export const toMask = (opt: SubscribeMaskOptions = {}): ChangeMask => {
   if (opt.dirty) tags.push(ChangeTag.Dirty);
   if (opt.reset) tags.push(ChangeTag.Reset);
 
+  // Combine all selected tags into a single mask
   return addTag(0, ...tags);
 };

primitives/filed-form /src/form-core/middleware.ts

@@ -1,49 +1,91 @@
+/**
+ * Form middleware system for action processing and validation
+ * Provides type-safe action definitions and middleware composition utilities
+ */
+
 import type { AllPathsKeys, PathToDeepType } from 'skyroc-type-utils';
 
-import type { MetaShapeFromPaths } from '../react/hooks/FieldContext';
 import type { NamePath } from '../utils/util';
 
 import type { ValidateOptions } from './validation';
 
+/**
+ * Extended validation options for validating multiple fields
+ */
 export interface ValidateFieldsOptions extends ValidateOptions {
+  /** Only validate fields that have been modified (dirty) */
   dirty?: boolean;
 }
 
+/**
+ * Available array operations for form field arrays
+ */
 export type ArrayOp = 'insert' | 'move' | 'remove' | 'replace' | 'swap';
 
+/**
+ * Arguments for different array operations
+ * Each operation type has its own specific argument structure
+ */
 export type ArrayOpArgs =
-  | { index: number; item: any; op: 'insert' }
-  | { index: number; op: 'remove' }
-  | { from: number; op: 'move'; to: number }
-  | { from: number; op: 'swap'; to: number }
-  | { index: number; item: any; op: 'replace' };
+  | { index: number; item: any; op: 'insert' } // Insert item at index
+  | { index: number; op: 'remove' } // Remove item at index
+  | { from: number; op: 'move'; to: number } // Move item from one index to another
+  | { from: number; op: 'swap'; to: number } // Swap items at two indices
+  | { index: number; item: any; op: 'replace' }; // Replace item at index
 
+/**
+ * Utility type to extract arguments for a specific array operation
+ */
 export type ArgsOf<T extends ArrayOp> = Extract<ArrayOpArgs, { op: T }>;
 
+/**
+ * Action type for array operations on form fields
+ */
 export type ArrayOpAction = { args: ArgsOf<ArrayOp>; name: NamePath; type: 'arrayOp' };
 
+/**
+ * Union type representing all possible form actions
+ * Each action type corresponds to a specific form operation
+ */
 export type Action<Values = any, T extends AllPathsKeys<Values> = AllPathsKeys<Values>> =
-  | { name: T; type: 'setFieldValue'; validate?: boolean; value: PathToDeepType<Values, T> }
-  | { type: 'setFieldsValue'; validate?: boolean; values: Values }
-  | { names?: T[]; type: 'reset' }
-  | { name: T; opts?: ValidateOptions; type: 'validateField' }
-  | { name?: T[]; opts?: ValidateFieldsOptions; type: 'validateFields' }
-  | { entries: Array<[T, string[]]>; type: 'setExternalErrors' }
-  | ArrayOpAction;
+  | { name: T; type: 'setFieldValue'; validate?: boolean; value: PathToDeepType<Values, T> } // Set single field value
+  | { type: 'setFieldsValue'; validate?: boolean; values: Values } // Set multiple field values
+  | { names?: T[]; type: 'reset' } // Reset fields to initial values
+  | { name: T; opts?: ValidateOptions; type: 'validateField' } // Validate single field
+  | { name?: T[]; opts?: ValidateFieldsOptions; type: 'validateFields' } // Validate multiple fields
+  | { entries: Array<[T, string[]]>; type: 'setExternalErrors' } // Set external validation errors
+  | ArrayOpAction; // Array operations
 
+/**
+ * Context object provided to middleware functions
+ * Contains methods to interact with the form state and dispatch actions
+ */
 export type MiddlewareCtx<Values, T extends AllPathsKeys<Values> = AllPathsKeys<Values>> = {
+  /** Dispatch an action to the form store */
   dispatch(a: Action<Values, T>): void;
-  getFields(): MetaShapeFromPaths<Values, T[]>;
+  /** Get current form state values */
   getState(): Values;
 };
 
+/**
+ * Middleware function type for form action processing
+ * Follows the standard middleware pattern: (ctx) => (next) => (action) => void
+ * Allows intercepting and modifying form actions before they reach the store
+ */
 export type Middleware<Values = any, T extends AllPathsKeys<Values> = AllPathsKeys<Values>> = (
   ctx: MiddlewareCtx<Values, T>
 ) => (next: (a: Action<Values, T>) => void) => (a: Action<Values, T>) => void;
 
+/**
+ * Composes multiple functions into a single function
+ * Used to combine multiple middleware functions into a single middleware chain
+ */
 export function compose(...fns: ((...args: any[]) => any)[]) {
+  // No functions provided, return identity function
   if (fns.length === 0) return (arg: any) => arg;
+  // Single function, return it directly
   if (fns.length === 1) return fns[0];
+  // Multiple functions, compose them right-to-left
   return fns.reduce(
     (a, b) =>
       (...args: any[]) =>