# @mdsfe/toolkit

[English](./README.md) | [简体中文](./README.zh-CN.md)

`@mdsfe/toolkit` is a lightweight, modular TypeScript utility library for browser-friendly app development. It borrows the practical layering ideas from `epfe-utils`, but removes business coupling so the package can be shared, published, and maintained as a public npm library.

## Why Open Source

- Build a reusable foundation instead of a one-off internal helper set
- Lower adoption cost with clearer docs, stable exports, and public package metadata
- Make external collaboration, issue tracking, and npm publishing straightforward
- Keep business modules separate from general-purpose utilities

## Features

- Runtime dependency-free
- TypeScript-first with generated declarations
- Function-style APIs plus optional `*Utils` class facades
- Tree-shakeable subpath exports
- Safe in browser-first projects and import-friendly in non-browser environments

## Modules

```text
src/
  browser/     Query parsing, storage wrappers, runtime detection
  format/      Date, bytes, number, currency formatting
  function/    Debounce, throttle, memoize, retry, compose, pipe, curry
  object/      Deep clone, isEmpty, pick, omit
  string/      HTML escaping, keyword highlight, whitespace cleanup
  types/       Shared public type definitions
  validation/  Rule-based object validation helpers
```

## Installation

```bash
npm install @mdsfe/toolkit
```

## Quick Start

```ts
import {
  debounce,
  deepClone,
  formatDate,
  parseQuery,
  validate,
  required,
  email,
} from '@mdsfe/toolkit';

const profile = deepClone({
  name: 'Alice',
  email: 'alice@example.com',
});

const query = parseQuery('https://example.com?a=1&a=2&b=3');
const rules = [required('name'), email('email')];
const result = validate(profile, rules);

const log = debounce((value: string) => console.log(value), 200);

console.log(formatDate(Date.now(), 'YYYY-MM-DD HH:mm:ss'));
console.log(query, result.isValid);
log('toolkit');
```

## Class-Style Usage

```ts
import {
  BrowserUtils,
  CommonUtils,
  FormatUtils,
  FunctionUtils,
  ValidationUtils,
} from '@mdsfe/toolkit';

const cloned = CommonUtils.deepClone({ id: 1 });
const date = FormatUtils.formatDate(Date.now(), 'YYYY-MM-DD');
const query = BrowserUtils.getUrlAllParams('https://example.com?a=1');
const handler = FunctionUtils.debounce(() => console.log('run'), 150);
const result = ValidationUtils.validate(
  { name: 'toolkit' },
  [ValidationUtils.required('name')]
);

console.log(cloned, date, query, result.isValid);
handler();
```

## Subpath Imports

```ts
import { parseQuery } from '@mdsfe/toolkit/browser';
import { debounce, retry } from '@mdsfe/toolkit/function';
import { deepClone, isEmpty } from '@mdsfe/toolkit/object';
import { compactWhitespace, highlightKeyword } from '@mdsfe/toolkit/string';
import { formatBytes, formatCurrency } from '@mdsfe/toolkit/format';
import { validate, required } from '@mdsfe/toolkit/validation';
```

## Compatibility Helpers

To ease migration from `epfe-utils`, `toolkit` keeps several familiar helpers with safer implementations:

- `getUrlAllParams`
- `getUrlQuery`
- `getSession`
- `setSession`
- `getUserOsInfo`
- `isImageUrl`
- `paddingZero`

## Development

```bash
npm install
npm run build
npm run typecheck
npm run release:check
```

## Roadmap

- Keep the public API small and stable
- Add tests before wider npm distribution
- Publish `@mdsfe/toolkit` to npm once the `mdsfe` scope publish permission is ready
- Leave business-specific adapters outside this package

## Open Source Docs

- [中文说明](./README.zh-CN.md)
- [Contributing](./CONTRIBUTING.md)
- [Code of Conduct](./CODE_OF_CONDUCT.md)
- [Security Policy](./SECURITY.md)
- [Changelog](./CHANGELOG.md)
- [License](./LICENSE)