### Installation Commands

Source: https://github.com/gaubee/std/blob/main/util/README-zh.md

Provides installation instructions for the @gaubee/util library across different package managers and environments.

```bash
# Deno (JSR)
denodenpm install @gaubee/util

# NPM
npm install @jsr/gaubee__util

# Yarn
yarn add @jsr/gaubee__util

# PNPM
pnpm add @jsr/gaubee__util
```

--------------------------------

### Install @gaubee/nodekit

Source: https://github.com/gaubee/std/blob/main/nodekit/README.md

Instructions for installing the @gaubee/nodekit package using different package managers via JSR.

```bash
# JSR (deno)
denp add @gaubee/nodekit
```

```bash
# JSR (npm)
npx jsr add @gaubee/nodekit
```

```bash
# JSR (pnpm)
pnpm dlx jsr add @gaubee/nodekit
```

```bash
# JSR (yarn)
yarn dlx jsr add @gaubee/nodekit
```

--------------------------------

### Installation

Source: https://github.com/gaubee/std/blob/main/node/README.md

Instructions for installing the @gaubee/node package using various package managers like pnpm, npm, yarn, and deno.

```bash
# pnpm
pnpm add @gaubee/node
# npm
npm install @gaubee/node
# yarn
yarn add @gaubee/node
# jsr
deno add @gaubee/node
```

--------------------------------

### Basic Usage Example

Source: https://github.com/gaubee/std/blob/main/node/README.md

A simple TypeScript example demonstrating how to import and use the `cwdResolver` function from the @gaubee/node package.

```typescript
import { cwdResolver } from "@gaubee/node/path";

console.log(cwdResolver("file.txt"));
```

--------------------------------

### Install @gaubee/flow

Source: https://github.com/gaubee/std/blob/main/flow/README.md

Provides installation commands for various package managers and environments like npm, pnpm, yarn, deno, and bun. It also shows how to add the package using JSR.

```bash
npm install @gaubee/flow
pnpm install @gaubee/flow
yarn install @gaubee/flow
deno add npm:@gaubee/flow
bun add @gaubee/flow

deno add jsr:@gaubee/flow
npx jsr add @gaubee/flow
yarn dlx jsr add @gaubee/flow
pnpm dlx jsr add @gaubee/flow
bunx jsr add @gaubee/flow
```

--------------------------------

### Install @gaubee/node

Source: https://github.com/gaubee/std/blob/main/node/README-zh.md

Instructions for installing the @gaubee/node package using different package managers like pnpm, npm, yarn, and deno (via jsr).

```bash
# pnpm
pnpm add @gaubee/node
# npm
npm install @gaubee/node
# yarn
yarn add @gaubee/node
# jsr
denop add @gaubee/node
```

--------------------------------

### Install @gaubee/nodekit

Source: https://github.com/gaubee/std/blob/main/nodekit/README-zh.md

Provides installation commands for @gaubee/nodekit using different package managers and environments like JSR, Deno, npm, pnpm, and yarn.

```bash
# JSR (deno)
deno add @gaubee/nodekit
```

```bash
# JSR (npm)
npx jsr add @gaubee/nodekit
```

```bash
# JSR (pnpm)
pnpm dlx jsr add @gaubee/nodekit
```

```bash
# JSR (yarn)
yarn dlx jsr add @gaubee/nodekit
```

--------------------------------

### Basic Usage Example

Source: https://github.com/gaubee/std/blob/main/util/README-zh.md

Demonstrates how to import and use utility functions like arr_set_next and date_clone from the @gaubee/util library in a TypeScript environment.

```typescript
import { arr_set_next, date_clone } from "@gaubee/util";

const myArray = [1, 2, 3];
arr_set_next(myArray, 4);
console.log(myArray); // [1, 2, 3, 4]

const originalDate = new Date();
const clonedDate = date_clone(originalDate);
console.log(clonedDate !== originalDate); // true
console.log(clonedDate.getTime() === originalDate.getTime()); // true
```

--------------------------------

### Basic Usage Example

Source: https://github.com/gaubee/std/blob/main/node/README-zh.md

Demonstrates how to import and use the `cwdResolver` function from the `@gaubee/node/path` module in a TypeScript environment.

```typescript
import { cwdResolver } from "@gaubee/node/path";

console.log(cwdResolver("file.txt"));
```

--------------------------------

### Import @gaubee/nodekit

Source: https://github.com/gaubee/std/blob/main/nodekit/README.md

Example of how to import functions or modules from the @gaubee/nodekit package into a TypeScript project.

```typescript
import { someFunction } from "@gaubee/nodekit"; // or specific module like "@gaubee/nodekit/fs"
// Your code here
```

--------------------------------

### Applying TC39 Shim Effects Globally

Source: https://github.com/gaubee/std/blob/main/tc39-shim/README-zh.md

Demonstrates how to use `applyEffect` to globally install various TC39 shim functionalities, including Promise extensions and Set operations. This approach is used for polyfilling or applying shims to the native objects.

```TypeScript
import {
  applyEffect,
  promise_with_resolvers,
  set_difference,
  set_intersection,
  set_is_disjoint_from,
  set_is_subset_of,
  set_is_superset_of,
  set_symmetric_difference,
  set_union,
} from "@gaubee/tc39-shim";

applyEffect(promise_with_resolvers, set_union, set_intersection, set_difference, set_symmetric_difference, set_is_subset_of, set_is_superset_of, set_is_disjoint_from);
```

--------------------------------

### map_get_or_put: Get or Create Map Value

Source: https://github.com/gaubee/std/blob/main/util/README-zh.md

Retrieves a value from a Map by its key. If the key does not exist, it calls a provided `put` function to create the value, stores it in the Map, and then returns the newly created value.

```typescript
map_get_or_put<T extends CommonMap<GetMapKey<T>, GetMapValue<T>>, K extends GetMapKey<T>>(map: T, key: K, put: (key: K, map: T) => GetMapValue<T>): GetMapValue<T>
// 读取 Map 中的值，如果键不存在，则调用 `put` 函数创建值，存入 Map 并返回该值。
```

--------------------------------

### map_get_or_put_async: Async Get or Create Map Value

Source: https://github.com/gaubee/std/blob/main/util/README-zh.md

Asynchronously retrieves a value from a Map by its key. If the key does not exist, it asynchronously calls a provided `put` function to create the value, stores it, and returns it. It includes mutex locking to prevent concurrency issues during asynchronous creation.

```typescript
map_get_or_put_async<T extends CommonMap<GetMapKey<T>, GetMapValue<T>>, K extends GetMapKey<T>>(map: T, key: K, put: (key: K, map: T) => PromiseMaybe<GetMapValue<T>>): Promise<GetMapValue<T>>
// 异步地读取 Map 中的值。如果键不存在，则异步调用 `put` 函数创建值，存入 Map 并返回该值。此函数在异步创建过程中会进行互斥锁定，以防止并发问题。
```

--------------------------------

### API Documentation for @gaubee/node

Source: https://github.com/gaubee/std/blob/main/node/README-zh.md

Comprehensive API documentation for the @gaubee/node package, detailing functions for environment variable sourcing, path resolution, and promise utilities.

```APIDOC
API Documentation for @gaubee/node

## env

- `viteEnvSource`:
  - `(): Record<string, string>`
  - 获取 Vite 环境变量源。
- `nodeEnvSource`:
  - `(): Record<string, string>`
  - 获取 Node.js 环境变量源 (process.env)。
- `denoEnvSource`:
  - `(): Record<string, string>`
  - 获取 Deno 环境变量源。
- `bunEnvSource`:
  - `(): Record<string, string>`
  - 获取 Bun 环境变量源。
- `storageEnvSource`:
  - `(storage?: Storage): Record<string, string>`
  - 获取基于 Storage API (如 sessionStorage) 的环境变量源。
- `autoEnvSource`:
  - `(fallback?: () => Record<string, string>): Record<string, string | undefined>`
  - 自动检测并返回当前环境的变量源 (Deno > Bun > Vite > Node.js > sessionStorage)。
- `defineEnv`:
  - `<P extends string, KV extends Record<string, EnvConfig>>(prefix: P, kv: KV, source?: Record<string, string | undefined>, ext?: object): DefineEnvChain<P, DefineEnv<P, KV>>`
  - 定义一组环境变量，支持类型转换、默认值和链式定义。

## path

- `normalizeFilePath`:
  - `(path: string | URL): string`
  - 将路径格式化为标准 POSIX 格式，支持 URL 和 Windows 路径。
- `createResolver`:
  - `(cwd: string): PathResolver`
  - 创建一个路径解析器，该解析器会相对于指定的 `cwd` (当前工作目录) 解析路径。
  - 返回的函数带有 `dirname` 属性，值为传入的 `cwd`。
- `cwdResolver`:
  - `PathResolver` (即 `((...paths: string[]) => string) & {dirname: string}`)
  - 基于当前 Node.js 进程的工作目录 (`process.cwd()`) 的路径解析器。
- `createResolverByRootFile`:
  - `(fromPath?: string | URL, rootFilename?: string): PathResolver`
  - 通过向上查找指定的根文件名 (默认为 `package.json`) 来创建路径解析器，解析器会基于包含该根文件的目录进行解析。

## promise

- `nodeTimmers`:
  - `{ eventEmitter: NodeTimmer.EventEmiter }`
  - 对 `@gaubee/util` 中 `timmers` 的扩展，提供了与 Node.js 事件相关的 Timmer。
  - `nodeTimmers.eventEmitter`: 一个 Timmer 工厂函数，用于为 `delay` 函数创建基于 `node:events/EventEmitter` 的 Timmer。可以监听指定事件，并在事件触发时解决
    Promise，支持可选的事件参数过滤器。
```

--------------------------------

### Environment Variable Sources API

Source: https://github.com/gaubee/std/blob/main/node/README.md

Documentation for various functions providing environment variable sources across different runtimes (Vite, Node.js, Deno, Bun) and storage APIs. Includes an auto-detection function and a type-safe definition utility.

```APIDOC
Environment Variable Sources API:

- viteEnvSource
  - `(): Record<string, string>`
  - Gets the Vite environment variable source.

- nodeEnvSource
  - `(): Record<string, string>`
  - Gets the Node.js environment variable source (process.env).

- denoEnvSource
  - `(): Record<string, string>`
  - Gets the Deno environment variable source.

- bunEnvSource
  - `(): Record<string, string>`
  - Gets the Bun environment variable source.

- storageEnvSource
  - `(storage?: Storage): Record<string, string>`
  - Gets an environment variable source based on the Storage API (e.g., sessionStorage).

- autoEnvSource
  - `(fallback?: () => Record<string, string>): Record<string, string | undefined>`
  - Automatically detects and returns the environment variable source for the current environment (Deno > Bun > Vite > Node.js > sessionStorage).

- defineEnv
  - `<P extends string, KV extends Record<string, EnvConfig>>(prefix: P, kv: KV, source?: Record<string, string | undefined>, ext?: object): DefineEnvChain<P, DefineEnv<P, KV>>`
  - Defines a set of environment variables, supporting type conversion, default values, and chained definitions.
```

--------------------------------

### Get All Property Descriptors in TypeScript

Source: https://github.com/gaubee/std/blob/main/util/README-zh.md

Retrieves all own property descriptors for an object, including non-enumerable properties and symbols. This function does not traverse the prototype chain.

```typescript
obj_all_descriptors<T extends object>(obj: T): Array<[prop: keyof T & (string | symbol), desp: PropertyDescriptor]>

- Gets all own property descriptors (excluding prototype chain properties) of an object.
```

--------------------------------

### map_delete_and_get: Delete and Get Map Value

Source: https://github.com/gaubee/std/blob/main/util/README-zh.md

Removes a key-value pair from a Map and returns the value that was deleted. If the key does not exist in the Map, it returns `undefined`.

```typescript
map_delete_and_get<T extends CommonMap<GetMapKey<T>, GetMapValue<T>>, K extends GetMapKey<T>>(map: T, key: K): GetMapValue<T> | undefined
// 从 Map 中删除一个键值对，并返回被删除的值。如果键不存在，则返回 `undefined`。
```

--------------------------------

### PNPM Publish Command

Source: https://github.com/gaubee/std/blob/main/nodekit/README.md

Executes the `pnpm publish` command to publish a package to a registry, with options for customization.

```APIDOC
pnpm API:

pnpm_publish(options: PnpmPublishOptions) => Promise<void>
  - Executes the `pnpm publish` command. The `PnpmPublishOptions` object can configure aspects of the publish process.
```

--------------------------------

### Path Utilities API

Source: https://github.com/gaubee/std/blob/main/node/README.md

API documentation for path manipulation functions. Includes utilities for normalizing paths, creating custom resolvers based on a current working directory, a default resolver for Node.js's cwd, and a resolver based on finding a root file like package.json.

```APIDOC
Path Utilities API:

- normalizeFilePath
  - `(path: string | URL): string`
  - Formats the path to standard POSIX format, supporting URL and Windows paths.

- createResolver
  - `(cwd: string): PathResolver`
  - Creates a path resolver that resolves paths relative to the specified `cwd` (current working directory).
  - The returned function has a `dirname` property with the value of the passed `cwd`.

- cwdResolver
  - `PathResolver` (i.e., `((...paths: string[]) => string) & {dirname: string}`)
  - A path resolver based on the current Node.js process's working directory (`process.cwd()`).

- createResolverByRootFile
  - `(fromPath?: string | URL, rootFilename?: string): PathResolver`
  - Creates a path resolver by looking up the specified root filename (defaults to `package.json`) upwards. The resolver will resolve paths based on the directory containing that root file.
```

--------------------------------

### Configuration File API

Source: https://github.com/gaubee/std/blob/main/nodekit/README.md

Provides functions for reading and writing various configuration file formats including JSON, YAML, and TOML. Includes options for default values and pre-write transformations.

```APIDOC
config_file API:

writeText(path: string, content: string) => void
  - Writes raw text content to the specified file path.

readJson<T = any>(path: string, defaultValue?: () => T) => T
  - Reads JSON or JSONC file content. Optionally provides a default value factory if the file is not found or invalid.

writeJson<T>(path: string, data: T, options?: JsonStringifyOptions, beforeWrite?: (jsonContent: string) => string) => void
  - Writes data to a file in JSON format. Allows custom stringify options and a pre-write hook.

readYaml<T = any>(path: string, defaultValue?: () => T) => T
  - Reads YAML file content. Optionally provides a default value factory if the file is not found or invalid.

writeYaml<T>(path: string, data: T, options?: YamlStringifyOptions, beforeWrite?: (yamlContent: string) => string) => void
  - Writes data to a file in YAML format. Allows custom stringify options and a pre-write hook.

readToml<T = any>(path: string, defaultValue?: () => T) => T
  - Reads TOML file content. Optionally provides a default value factory if the file is not found or invalid.

writeToml<T extends Record<PropertyKey, never>>(path: string, data: T, beforeWrite?: (tomlContent: string) => string) => void
  - Writes data to a file in TOML format. Allows a pre-write hook.
```

--------------------------------

### Array Element Removal by Value

Source: https://github.com/gaubee/std/blob/main/util/README-zh.md

Functions to remove elements from an array based on their value. Supports removing the first occurrence, last occurrence, or multiple occurrences from the start or end of the array up to a specified limit.

```typescript
arr_remove_first<T>(arr: T[], value: T): number
```

```typescript
arr_remove_start<T>(arr: T[], value: T, limit: number): number
```

```typescript
arr_remove_last<T>(arr: T[], value: T): number
```

```typescript
arr_remove_end<T>(arr: T[], value: T, limit: number): number
```

--------------------------------

### File System Entry Classes and Traversal

Source: https://github.com/gaubee/std/blob/main/nodekit/README-zh.md

Defines classes for representing file system entries (FileEntry, DirectoryEntry) and a utility for recursively walking directory trees.

```APIDOC
fs:
  FileEntry:
    - class FileEntry extends Entry
    - Represents a file system file. Provides methods for reading (text, JSON, YAML, TOML, Markdown) and writing.
    - Key methods: `read()`, `readText()`, `readJson()`, `readYaml()`, `readToml()`, `write()`, `writeJson()`, `writeYaml()`, `writeToml()`, `updateText()`, `readMarkdown()`, `writeMarkdown()`.
  DirectoryEntry:
    - class DirectoryEntry extends Entry
    - Represents a file system directory.
  walkAny(rootpath: string, options?: WalkOptions) => Generator<WalkEntry, void, void>
    - Traverses files and directories recursively from a root path. Returns a generator that can be filtered by options.
```

--------------------------------

### PNPM Publish Command

Source: https://github.com/gaubee/std/blob/main/nodekit/README-zh.md

Utility to execute the `pnpm publish` command for publishing packages.

```APIDOC
pnpm:
  pnpm_publish(options: PnpmPublishOptions) => Promise<void>
    - Executes the `pnpm publish` command to publish a package.
```

--------------------------------

### Configuration File Operations

Source: https://github.com/gaubee/std/blob/main/nodekit/README-zh.md

API for reading and writing configuration files in JSON, YAML, and TOML formats. Includes options for default values and pre-write transformations.

```APIDOC
config_file:
  writeText(path: string, content: string) => void
    - Writes text content to a specified file path.
  readJson<T = any>(path: string, defaultValue?: () => T) => T
    - Reads JSON or JSONC file content. Optionally provides a default value factory.
  writeJson<T>(path: string, data: T, options?: JsonStringifyOptions, beforeWrite?: (jsonContent: string) => string) => void
    - Writes data to a file in JSON format. Supports custom stringify options and a pre-write hook.
  readYaml<T = any>(path: string, defaultValue?: () => T) => T
    - Reads YAML file content. Optionally provides a default value factory.
  writeYaml<T>(path: string, data: T, options?: YamlStringifyOptions, beforeWrite?: (yamlContent: string) => string) => void
    - Writes data to a file in YAML format. Supports custom stringify options and a pre-write hook.
  readToml<T = any>(path: string, defaultValue?: () => T) => T
    - Reads TOML file content. Optionally provides a default value factory.
  writeToml<T extends Record<PropertyKey, never>>(path: string, data: T, beforeWrite?: (tomlContent: string) => string) => void
    - Writes data to a file in TOML format. Supports a pre-write hook.
```

--------------------------------

### Shell Execution API

Source: https://github.com/gaubee/std/blob/main/nodekit/README.md

Provides utilities for executing shell commands, offering both a configurable shell instance and a pre-configured default instance.

```APIDOC
shell API:

$ (pre-configured instance)
  - A default `Shell` instance pre-configured for running terminal commands.
  - Key capabilities include: `$.spawn()` for spawning processes, accessing `$.cwd` and `$.env` for environment configuration, and utility methods like `$.ls()` and `$.colors`.

$$ (configurable instance)
  - `(options: CreateShellOptions) => Shell`
  - Creates a new, customizable `Shell` executor instance. Allows specifying options such as the current working directory (`cwd`) and environment variables (`env`).
```

--------------------------------

### File System Entry API

Source: https://github.com/gaubee/std/blob/main/nodekit/README.md

Defines classes for representing file system entries (files and directories) and a utility for recursively walking directory trees.

```APIDOC
fs API:

FileEntry
  - class FileEntry extends Entry
  - Represents a file in the file system. Provides methods for reading (text, JSON, YAML, TOML), writing, and updating file content, including Markdown.
  - Key methods: `read()`, `readText()`, `readJson()`, `readYaml()`, `readToml()`, `write()`, `writeJson()`, `writeYaml()`, `writeToml()`, `updateText()`, `readMarkdown()`, `writeMarkdown()`.

DirectoryEntry
  - class DirectoryEntry extends Entry
  - Represents a directory in the file system.

walkAny(rootpath: string, options?: WalkOptions) => Generator<WalkEntry, void, void>
  - Walks through files and directories starting from `rootpath`, including subdirectories. Returns a generator yielding `WalkEntry` objects. Can be filtered using `WalkOptions`.
```

--------------------------------

### Shell Execution Utilities

Source: https://github.com/gaubee/std/blob/main/nodekit/README-zh.md

Provides utilities for executing shell commands, including a configurable shell instance and a pre-configured default instance.

```APIDOC
shell:
  $$ (options: CreateShellOptions) => Shell
    - Creates a new, configurable shell executor instance. Allows customization of current working directory (`cwd`) and environment variables (`env`).
  $ (Shell pre-configured instance)
    - A pre-configured shell executor instance for running terminal commands.
    - Key capabilities: `$.spawn()`, `$.cwd`, `$.env`, `$.ls()`, `$.colors`.
```

--------------------------------

### Abort Signal Utilities

Source: https://github.com/gaubee/std/blob/main/util/README-zh.md

API documentation for functions related to managing AbortSignals, including creating timed signals, merging signals, and converting signals to promises.

```APIDOC
abort_fused_timeout(ms: number, options?: { parentSignal?: AbortSignal | null | undefined; } | undefined): AbortSignal
  - Creates an AbortSignal that automatically aborts after a specified number of milliseconds.
  - Optionally links to a parent AbortSignal, aborting if the parent aborts or the timeout occurs.

abort_signal_from_any(...signals: AbortSignal[]): AbortSignal
  - Creates a new AbortSignal that aborts when any of the provided input AbortSignals abort.

abort_signal_merge(...signals: AbortSignal[]): AbortSignal
  - Merges multiple AbortSignals. The returned Signal aborts only when all provided Signals have aborted.

abort_signal_promisify(input: AbortSignal | {signal: AbortSignal}): Promise<never>
  - Converts an AbortSignal into a Promise that rejects with the signal's reason when it aborts.
  - Caches the result for repeated calls with the same AbortSignal.

abort_signal_race<T>(signal: AbortSignal, fn_or_promise: PromiseLike<T> | (() => PromiseLike<T>)): PromiseMaybe<T>
  - Races a Promise or a function returning a Promise against an AbortSignal.
  - If the signal is already aborted, it throws the reason immediately.
  - If the signal aborts before the Promise completes, the result Promise rejects with the signal's reason.
  - Otherwise, the result Promise follows the outcome of `fn_or_promise`.
```

--------------------------------

### Terminal UI Components

Source: https://github.com/gaubee/std/blob/main/nodekit/README-zh.md

Re-exports of popular libraries for creating interactive command-line interfaces, specifically for prompts and spinners.

```APIDOC
tui:
  prompts:
    - (Re-export of `@inquirer/prompts`)
    - Used for creating interactive command-line prompts.
  spinner:
    - (Re-export of `ora`)
    - Used for displaying terminal loading animations.
```

--------------------------------

### Legacy Setter Decorator

Source: https://github.com/gaubee/std/blob/main/util/README-zh.md

Facilitates the application of legacy decorator patterns for class setter methods. It requires the class and a builder function for the setter.

```APIDOC
legacySetter<C extends Class, V>(Class: C, builder: ClassSetterLegacyDecorator<InstanceType<C>, V>): ClassSetterDecorator<InstanceType<C>, V>

Description:
  Used to apply legacy decorator patterns within standard setter decorators.

Parameters:
  - Class: The class to which the decorator is applied.
  - builder: A function conforming to the ClassSetterLegacyDecorator type, which handles the legacy setter logic.
    Type: (target: T, property: PropertyKey<T>, descriptor: RequiredKeys<TypedPropertyDescriptor<V>, "set">) => void | TypedPropertyDescriptor<V>

Returns:
  A ClassSetterDecorator instance.
```

--------------------------------

### Import @gaubee/nodekit

Source: https://github.com/gaubee/std/blob/main/nodekit/README-zh.md

Demonstrates how to import functionality from the @gaubee/nodekit library into a TypeScript project, showing both general and specific module imports.

```typescript
import {someFunction} from "@gaubee/nodekit"; // 或者具体模块如 "@gaubee/nodekit/fs"
// Your code here
```

--------------------------------

### Terminal Color Formatting

Source: https://github.com/gaubee/std/blob/main/nodekit/README-zh.md

Re-exports the `@std/fmt/colors` library, providing a comprehensive set of tools for adding color and styling to terminal output.

```APIDOC
colors:
  - (Re-export of `@std/fmt/colors`)
  - Provides a full suite of tools for terminal output coloring and styling.
```

--------------------------------

### Legacy Method Decorator

Source: https://github.com/gaubee/std/blob/main/util/README-zh.md

Allows the use of legacy decorator patterns for class methods. It takes the class and a builder function that defines the legacy method behavior.

```APIDOC
legacyMethod<C extends Class, M extends Func<InstanceType<C>>>(Class: C, builder: ClassMethodLegacyDecorator<InstanceType<C>, M>): ClassMethodDecorator<InstanceType<C>, M>

Description:
  Used to apply legacy decorator patterns within standard method decorators.

Parameters:
  - Class: The class to which the decorator is applied.
  - builder: A function conforming to the ClassMethodLegacyDecorator type, which handles the legacy method logic.
    Type: (target: T, property: PropertyKey<T>, descriptor: RequiredKeys<TypedPropertyDescriptor<M>, "value">) => void

Returns:
  A ClassMethodDecorator instance.
```

--------------------------------

### ReadableStream with Controller

Source: https://github.com/gaubee/std/blob/main/util/README-zh.md

A convenient constructor for ReadableStream that directly exposes the controller object. It utilizes PureEvent to expose 'pull' and 'cancel' events, simplifying stream management.

```APIDOC
rs_with_controller: ReadableByteWithController

Description:
  A helper function to create ReadableStreams with direct access to the controller and event hooks for pull and cancel operations.

Parameters:
  - `ReadableByteWithController`: Likely a function or class constructor that takes an object with `start`, `pull`, and `cancel` methods.
    - `start`: Called when the stream is initialized.
    - `pull`: Called when the consumer wants more data. Can be hooked via `PureEvent`.
    - `cancel`: Called when the stream is cancelled. Can be hooked via `PureEvent`.

Example:
  ```ts
  import { rs_with_controller } from "@gaubee/util";
  import { PureEvent } from "@gaubee/util";

  const pullEvent = new PureEvent<void>();
  const cancelEvent = new PureEvent<void>();

  const readableStream = rs_with_controller({
    start(controller) {
      // Initial setup
      controller.enqueue(new TextEncoder().encode("Hello"));
    },
    pull(controller) {
      // Hook into pull event
      pullEvent.on(() => {
        controller.enqueue(new TextEncoder().encode("More data"));
        if (/* end condition */) {
          controller.close();
        }
      });
    },
    cancel() {
      // Hook into cancel event
      cancelEvent.on(() => {
        console.log("Stream cancelled");
      });
    }
  });

  // To trigger pull:
  // pullEvent.emit();
  // To trigger cancel:
  // cancelEvent.emit();
  ```
```

--------------------------------

### Legacy Class Decorator

Source: https://github.com/gaubee/std/blob/main/util/README-zh.md

Provides a way to use legacy decorator patterns for class decoration itself. It takes a builder function that defines the legacy class logic.

```APIDOC
legacyClass<C extends Class>(builder: ClassLegacyDecorator<C>): ClassDecorator<C>

Description:
  Used to apply legacy decorator patterns within standard class decorators.

Parameters:
  - builder: A function conforming to the ClassLegacyDecorator type, which handles the legacy class logic.
    Type: (target: C) => void

Returns:
  A ClassDecorator instance.
```

--------------------------------

### Legacy Accessor Decorator

Source: https://github.com/gaubee/std/blob/main/util/README-zh.md

Provides a way to use legacy decorator patterns for class accessors (getters/setters). It takes the class and a builder function that defines the legacy accessor logic.

```APIDOC
legacyAccessor<C extends Class, V>(Class: C, builder: ClassAccessorLegacyDecorator<InstanceType<C>, V>): ClassAccessorDecorator<InstanceType<C>, V>

Description:
  Used to apply legacy decorator patterns within standard accessor decorators.

Parameters:
  - Class: The class to which the decorator is applied.
  - builder: A function conforming to the ClassAccessorLegacyDecorator type, which handles the legacy accessor logic.
    Type: (target: T, property: PropertyKey<T>, descriptor: RequiredKeys<TypedPropertyDescriptor<V>, "get" | "set">) => void | TypedPropertyDescriptor<V>

Returns:
  A ClassAccessorDecorator instance.
```

--------------------------------

### Legacy Getter Decorator

Source: https://github.com/gaubee/std/blob/main/util/README-zh.md

Enables the use of legacy decorator patterns specifically for class getter methods. It accepts the class and a builder function for the getter.

```APIDOC
legacyGetter<C extends Class, V>(Class: C, builder: ClassGetterLegacyDecorator<InstanceType<C>, V>): ClassGetterDecorator<InstanceType<C>, V>

Description:
  Used to apply legacy decorator patterns within standard getter decorators.

Parameters:
  - Class: The class to which the decorator is applied.
  - builder: A function conforming to the ClassGetterLegacyDecorator type, which handles the legacy getter logic.
    Type: (target: T, property: PropertyKey<T>, descriptor: RequiredKeys<TypedPropertyDescriptor<V>, "get">) => void | TypedPropertyDescriptor<V>

Returns:
  A ClassGetterDecorator instance.
```

--------------------------------

### Markdown File API

Source: https://github.com/gaubee/std/blob/main/nodekit/README.md

Utilities for reading and writing Markdown files, including support for front-matter parsing via re-exporting the 'gray-matter' library.

```APIDOC
markdown_file API:

matter
  - (Re-export of `gray-matter` library)
  - Re-exports the `gray-matter` library for handling Markdown front-matter.

readMarkdown(path: string, options?: MarkdownOptions) => matter.GrayMatterFile<string>
  - Reads Markdown file content and its front-matter. Returns a GrayMatterFile object.

writeMarkdown(path: string, content: string, data?: object, options?: MarkdownOptions) => void
  - Writes content and front-matter data to a Markdown file. Allows specifying data and options.
```

--------------------------------

### Basic SharedFlow Usage in TypeScript

Source: https://github.com/gaubee/std/blob/main/flow/README.md

Demonstrates basic event listening, dispatching, and removal using SharedFlow. Includes custom key listeners and listeners with dispose functions that can be awaited.

```ts
import { SharedFlow } from "@gaubee/flow";
const shared_flow = new SharedFlow<string>();

// add listen
const off = shared_flow.on((data) => console.log("on", data));
// dispatch listen
shared_flow.emit("hi");
// remove listen
off();

// add listen with custom key
shared_flow.on((data) => console.log("on", data), { key: "key1" });
// remove listen with custom key
shared_flow.off("key1");

// add listen width dispose function
const off = shared_flow.on((data) => console.log("on", data), {
  onDispose: async () => {
    console.log("off");
    return 123;
  },
});
// remove listen and run dispatch function
console.log(await off()); // { status: "fulfilled", value: 123 }
```

--------------------------------

### Memoize Legacy Decorator Factory

Source: https://github.com/gaubee/std/blob/main/util/README-zh.md

Creates a legacy decorator that memoizes (caches) the results of a class method. It can optionally accept a function to generate cache keys.

```APIDOC
decorator_make_memoize_legacy(key_fun?: ((...args: any[]) => any) | undefined): (target: any, prop_name: string, desc: PropertyDescriptor) => void

Description:
  Creates a legacy decorator for memoizing class method results.

Parameters:
  - key_fun: An optional function to generate cache keys based on method arguments.
    Type: ((...args: any[]) => any) | undefined

Returns:
  A decorator function that can be applied to class methods.
```

--------------------------------

### Promise Timers Object

Source: https://github.com/gaubee/std/blob/main/util/README-zh.md

An object providing various timer creation functions based on setTimeout, requestAnimationFrame, queueMicrotask, or EventTarget. It offers a unified interface for different timing mechanisms.

```APIDOC
timmers: { 
  timeout: (ms: number) => Timmer<void>; 
  raf: Timmer<number>; 
  microtask: Timmer<void>; 
  eventTarget: <T extends Event>(target: Pick<EventTarget, "addEventListener" | "removeEventListener">, eventType: string, filter?: ((event: T) => boolean | void) | undefined) => Timmer<T>; 
  from: <T extends number | Timmer<any>>(ms: T) => Timmer.From<T>; 
}

Description:
  An object containing multiple timer creation functions.
  - `timeout(ms)`: Creates a timer that resolves after `ms` milliseconds using `setTimeout`.
  - `raf`: Creates a timer that resolves with the current frame number using `requestAnimationFrame`.
  - `microtask`: Creates a timer that resolves using `queueMicrotask`.
  - `eventTarget(target, eventType, filter)`: Creates a timer that resolves when a specific event is dispatched on the `target`.
  - `from(ms)`: Creates a timer from a millisecond value or another `Timmer` instance.
```

--------------------------------

### Debounce Legacy Decorator Factory

Source: https://github.com/gaubee/std/blob/main/util/README-zh.md

Creates a legacy decorator that applies debouncing to a class method. It takes the wait time in milliseconds and optional configuration for debounce behavior.

```APIDOC
decorator_make_debounce_legacy(wait_ms: number, options?: { maxWait?: number | undefined; leading?: boolean | undefined; trailing?: boolean | undefined; } | undefined): (target: any, prop_name: string, desc: PropertyDescriptor) => void

Description:
  Creates a legacy decorator for debouncing class methods.

Parameters:
  - wait_ms: The number of milliseconds to delay.
  - options: Optional configuration for debounce behavior.
    - maxWait: The maximum time `func` is allowed to be delayed before it's invoked.
    - leading: Specify invoking on the leading edge of the timeout.
    - trailing: Specify invoking on the trailing edge of the timeout.

Returns:
  A decorator function that can be applied to class methods.
```

--------------------------------

### Legacy Field Decorator

Source: https://github.com/gaubee/std/blob/main/util/README-zh.md

Enables the application of legacy decorator patterns for class fields. It requires the class and a builder function for the field.

```APIDOC
legacyField<C extends Class, V>(Class: C, builder: ClassFieldLegacyDecorator<InstanceType<C>>): ClassFieldDecorator<InstanceType<C>, V>

Description:
  Used to apply legacy decorator patterns within standard field decorators.

Parameters:
  - Class: The class to which the decorator is applied.
  - builder: A function conforming to the ClassFieldLegacyDecorator type, which handles the legacy field logic.
    Type: (target: T, property: PropertyKey<T>) => void

Returns:
  A ClassFieldDecorator instance.
```

--------------------------------

### Apply Global Effects with TC39 Shims

Source: https://github.com/gaubee/std/blob/main/tc39-shim/README.md

Demonstrates how to apply global effects (polyfill) for various TC39 shim functionalities using the `applyEffect` function. This includes promise and set extension methods.

```typescript
import {
  applyEffect,
  promise_with_resolvers,
  set_difference,
  set_intersection,
  set_is_disjoint_from,
  set_is_subset_of,
  set_is_superset_of,
  set_symmetric_difference,
  set_union,
} from "@gaubee/tc39-shim";

applyEffect(promise_with_resolvers, set_union, set_intersection, set_difference, set_symmetric_difference, set_is_subset_of, set_is_superset_of, set_is_disjoint_from);
```

--------------------------------

### Markdown File Operations

Source: https://github.com/gaubee/std/blob/main/nodekit/README-zh.md

API for reading and writing Markdown files, including support for front-matter parsing and manipulation via re-exporting the 'gray-matter' library.

```APIDOC
markdown_file:
  matter:
    - (Re-export of `gray-matter` library)
    - Processes Markdown front-matter.
  readMarkdown(path: string, options?: MarkdownOptions) => matter.GrayMatterFile<string>
    - Reads Markdown file content and its front-matter.
  writeMarkdown(path: string, content: string, data?: object, options?: MarkdownOptions) => void
    - Writes content and front-matter data to a Markdown file.
```

--------------------------------

### Create Disposable Group

Source: https://github.com/gaubee/std/blob/main/util/README-zh.md

Creates a group to manage a collection of disposable resources. When the group is disposed, all its managed resources are also disposed.

```typescript
create_disposable_group(): DisposableGroup
```

--------------------------------

### API: createAdoptedStyleSheets for Adopted StyleSheets

Source: https://github.com/gaubee/std/blob/main/web/README.md

Offers a more user-friendly interface for managing adoptedStyleSheets. It extends the array with custom methods for easier stylesheet manipulation, allowing direct modification for immediate effect.

```APIDOC
createAdoptedStyleSheets
  Description: Returns a more user-friendly adoptedStyleSheets for managing stylesheets.
  Directly changing elements in this array immediately applies the styles.

  Extended Array-Like Methods:
    remove: (item: CSSStyleSheet) => void
      Removes a specific CSSStyleSheet from the collection.
    toggle: (item: CSSStyleSheet, enable?: boolean) => void
      Toggles the presence or enablement of a CSSStyleSheet.
    replace: (oldItem: CSSStyleSheet | null | undefined, newItem: CSSStyleSheet) => void
      Replaces an existing CSSStyleSheet with a new one.

  Extended Map-Like Methods:
    has: (key: unknown) => boolean
      Checks if a stylesheet associated with a key exists.
    set: (key: unknown, item: CSSStyleSheet) => void
      Associates a CSSStyleSheet with a given key.
    delete: (key: unknown) => void
      Removes a stylesheet associated with a key.
    get: (key: unknown) => CSSStyleSheet | undefined
      Retrieves a CSSStyleSheet associated with a key.
```

--------------------------------

### Ignore File Matching

Source: https://github.com/gaubee/std/blob/main/nodekit/README-zh.md

A class for matching file paths against ignore rules, supporting formats like .gitignore.

```APIDOC
ignore:
  Ignore:
    - class Ignore
    - Matches file paths against various ignore rule styles (e.g., .gitignore, .npmignore).
    - Constructor: `new Ignore(rules: string[], cwd: string, option?: {style?: IgnoreStyle})`
    - Static method `fromIgnoreFile(filepath: string) => Ignore`
      - Creates an Ignore instance from a specified ignore rule file.
    - Method `isMatch(filepath: string) => boolean`
      - Checks if a given file path matches any of the loaded ignore rules.
```

--------------------------------

### Ignore File Matching API

Source: https://github.com/gaubee/std/blob/main/nodekit/README.md

A utility class for determining if file paths should be ignored based on standard ignore rule formats like .gitignore.

```APIDOC
ignore API:

Ignore
  - class Ignore
  - A class that implements file matching logic based on ignore rules.
  - Constructor: `new Ignore(rules: string[], cwd: string, option?: {style?: IgnoreStyle})`
    - `rules`: An array of ignore patterns.
    - `cwd`: The current working directory for path resolution.
    - `option`: Optional configuration, including the style of ignore rules.
  - Static method `fromIgnoreFile`:
    - `(filepath: string) => Ignore`
    - Creates an `Ignore` instance by loading rules from a specified ignore file (e.g., `.gitignore`).
  - Method `isMatch`:
    - `(filepath: string) => boolean`
    - Checks if the given `filepath` matches any of the loaded ignore rules. Returns `true` if ignored, `false` otherwise.
```

--------------------------------

### GF: GeneratorFunction Constructor

Source: https://github.com/gaubee/std/blob/main/util/README-zh.md

Provides the GeneratorFunction constructor, used for creating generator functions.

```typescript
GF: GeneratorFunction
// GeneratorFunction 的构造函数。
```