or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

collections.mdform-utilities.mdindex.mdobject-operations.mdreactive-patterns.mdstring-processing.mdtype-checking.mdvalidation.md
tile.json

index.mddocs/

@formily/shared

@formily/shared is a comprehensive utility functions collection specifically designed for the Formily form framework ecosystem. It provides type-safe operations on arrays, objects, strings, and advanced form data processing with zero dependencies (except for path manipulation and case conversion). The library serves as the foundational utility layer for other Formily packages and offers essential tools for building robust, type-safe form applications.

Package Information

  • Package Name: @formily/shared
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @formily/shared

Core Imports

import { 
  toArr, each, map, reduce, find, includes,
  isEqual, 
  isFn, isArr, isStr, isNum, isBool, isObj, isPlainObj,
  clone, shallowClone,
  isEmpty, isValid,
  camelCase, pascalCase, paramCase,
  merge, lazyMerge,
  uid,
  Subscribable
} from "@formily/shared";

For CommonJS:

const { 
  toArr, each, map, reduce, find, includes,
  isEqual, 
  isFn, isArr, isStr, isNum, isBool, isObj, isPlainObj,
  clone, shallowClone,
  isEmpty, isValid,
  camelCase, pascalCase, paramCase,
  merge, lazyMerge,
  uid,
  Subscribable
} = require("@formily/shared");

Basic Usage

import { 
  toArr, each, map, isEqual, clone, isEmpty, 
  camelCase, merge, uid, Subscribable 
} from "@formily/shared";

// Array utilities
const data = toArr("hello"); // ["hello"]
each([1, 2, 3], (item, index) => console.log(item, index));

// Type checking
if (isFn(someValue)) {
  someValue(); // TypeScript knows it's a function
}

// Object operations
const obj1 = { a: 1, b: 2 };
const obj2 = { b: 3, c: 4 };
const merged = merge(obj1, obj2); // { a: 1, b: 3, c: 4 }

// String operations
const snake = camelCase("hello-world"); // "helloWorld"

// Cloning and comparison
const original = { nested: { data: [1, 2, 3] } };
const copy = clone(original);
console.log(isEqual(original, copy)); // true

// Publisher-subscriber pattern
const publisher = new Subscribable<string>();
const unsubscribe = publisher.subscribe((data) => console.log(data));
publisher.notify("Hello World!");

Architecture

@formily/shared is organized into several key functional areas:

  • Collection Utilities: Universal operations for arrays, objects, and strings (each, map, reduce, find)
  • Type System: Comprehensive type checking functions with TypeScript type guards
  • Object Manipulation: Deep cloning, merging, and comparison utilities optimized for form data
  • String Processing: Case conversion and length calculation with Unicode support
  • Validation Helpers: Empty value checking and validation utilities
  • Reactive Patterns: Publisher-subscriber implementation for reactive programming
  • Form Utilities: Path manipulation, middleware support, and unique ID generation

Capabilities

Collection Operations

Universal iteration, transformation, and querying operations that work consistently across arrays, objects, and strings.

function toArr(val: any): any[];
function each<T>(val: T[] | string | object, iterator: Function, revert?: boolean): void;
function map<T, U>(val: T[] | string | object, iterator: Function, revert?: boolean): U[] | Record<string, U>;
function reduce<T, U>(val: T[] | string | object, iterator: Function, accumulator?: U, revert?: boolean): U;
function find<T>(val: T[] | string | object, iterator: Function, revert?: boolean): T;
function includes<T>(val: T[] | string, searchElement: T, revert?: boolean): boolean;
function move<T>(array: T[], fromIndex: number, toIndex: number): T[];

Collection Operations

Type Checking

Comprehensive type checking utilities with full TypeScript type guard support for runtime type safety.

function isFn(val: any): val is Function;
function isArr(val: any): val is any[];
function isStr(val: any): val is string;
function isNum(val: any): val is number;
function isBool(val: any): val is boolean;
function isObj(val: unknown): val is object;
function isPlainObj(val: any): val is object;
function isMap(val: any): val is Map<any, any>;
function isSet(val: any): val is Set<any>;
function isRegExp(val: any): val is RegExp;
function isReactElement(obj: any): boolean;
function isHTMLElement(target: any): target is EventTarget;

Type Checking

Object Operations

Advanced object manipulation including deep cloning, merging, and equality comparison with special handling for React elements, Moment objects, and Immutable.js.

function clone(values: any): any;
function shallowClone(values: any): any;
function isEqual(a: any, b: any): boolean;
function merge(target: any, source: any, options?: MergeOptions): any;
function lazyMerge<T extends object | Function>(target: T, ...args: T[]): any;

Object Operations

Validation and Empty Checking

Utilities for checking empty values and validation with comprehensive empty detection for all data types.

function isEmpty(val: any, strict?: boolean): boolean;
function isValid(val: any): boolean;
function isUndef(val: any): boolean;
function defaults(defaults_: any, targets: any): any;

Validation

String Processing

String manipulation utilities including case conversion and length calculation with ANSI code and Unicode support.

function stringLength(input: string): number;
function camelCase(str: string): string;
function pascalCase(str: string): string;
function paramCase(str: string): string;
function lowerCase(str: string): string;
function upperCase(str: string): string;

String Processing

Publisher-Subscriber Pattern

Reactive programming utilities with event subscription, filtering, and middleware support.

class Subscribable<Payload = any> {
  subscribe(callback?: Subscriber<Payload>): number;
  unsubscribe(index?: number): void;
  notify(payload?: Payload, silent?: boolean): void;
}

interface IMiddleware<Payload = any, Result = any> {
  (payload: Payload, next: (payload?: Payload) => Result): Result;
}

function applyMiddleware(payload: any, fns?: IMiddleware[]): Promise<any>;

Reactive Patterns

Form Utilities

Specialized utilities for form applications including path manipulation, unique ID generation, and deprecation warnings.

function uid(len?: number): string;
function deprecate<P1, P2, P3, P4, P5>(method: any, message?: string, help?: string): Function;
function instOf(value: any, cls: any): boolean;

// Re-exported from @formily/path
class FormPath {
  // Path manipulation methods
}
class FormPathPattern {
  // Path pattern methods
}

Form Utilities

Types

type Subscriber<S> = (payload: S) => void;

interface Subscription<S> {
  notify?: (payload: S) => void | boolean;
  filter?: (payload: S) => any;
}

interface IMiddleware<Payload = any, Result = any> {
  (payload: Payload, next: (payload?: Payload) => Result): Result;
}

// Iterator types for collection operations
type EachArrayIterator<T> = (currentValue: T, key: number) => void | boolean;
type EachStringIterator = (currentValue: string, key: number) => void | boolean;
type EachObjectIterator<T = any> = (currentValue: T, key: string) => void | boolean;
type MapArrayIterator<TItem, TResult> = (currentValue: TItem, key: number) => TResult;
type MapStringIterator<TResult> = (currentValue: string, key: number) => TResult;
type MapObjectIterator<TItem, TResult> = (currentValue: TItem, key: string) => TResult;