@wener/common 1.0.1

package/lib/tools/renderJsonSchemaToMarkdownDoc.js

@@ -0,0 +1,85 @@
+export function renderJsonSchemaToMarkdownDoc(rootSchema) {
+    // markdown
+    const out = [];
+    const all = new Set();
+    const pending = [];
+    const addObject = (o)=>{
+        if (all.has(o.$id)) {
+            return;
+        }
+        all.add(o.$id);
+        pending.push(o);
+    };
+    const writeObjectProps = (T, { prefix = '' } = {})=>{
+        if (!T?.properties) {
+            return;
+        }
+        for (const [name, schema] of Object.entries(T.properties)){
+            let typ = schema.$id || schema.type;
+            if (typ === 'array') {
+                typ = `${schema.items.$id || schema.items.type}[]`;
+                if (schema.items.$id) {
+                    addObject(schema.items);
+                }
+            } else if (schema.$id) {
+                addObject(schema);
+            }
+            if (!typ) {
+                if ('anyOf' in schema) {
+                    typ = 'enum';
+                }
+            }
+            out.push(`| ${prefix}${name} | ${typ} | ${schema.title || schema.description || ''} |`);
+            if (typ === 'object') {
+                writeObjectProps(schema, {
+                    prefix: `${prefix}${name}.`
+                });
+            } else if (schema.type === 'array') {
+                if (schema.items.type === 'object' && !schema.items.$id) {
+                    writeObjectProps(schema.items, {
+                        prefix: `${prefix}${name}[].`
+                    });
+                }
+            }
+        }
+    };
+    const writeObject = (T)=>{
+        out.push(`### ${T.title || T.$id}`);
+        out.push(`
+| $id | 名字 |
+| --- | --- |
+| ${T.$id || ''} | ${T.title || ''} | 
+    `);
+        if (T.description) {
+            out.push('');
+            out.push(`> ${T.description}`);
+            out.push('');
+        }
+        out.push(`| 名字 | 类型 | 说明 |`);
+        out.push(`| --- | --- | --- |`);
+        writeObjectProps(T);
+        out.push('');
+    };
+    writeObject(rootSchema);
+    for (const schema of pending){
+        if (schema.type === 'object') {
+            writeObject(schema);
+        } else if ('anyOf' in schema) {
+            out.push(`### ${schema.$id || schema.title}`);
+            out.push(`
+| $id | 名字 |
+| --- | --- |
+| ${schema.$id || ''} | ${schema.title || ''} | 
+    `);
+            out.push(`| 值 |  说明 |`);
+            out.push(`| --- | --- |`);
+            for (const item of schema.anyOf){
+                out.push(`| ${item.const} | ${item.title || item.description || ''} |`);
+            }
+            out.push('');
+        }
+    }
+    return out.join('\n');
+}
+
+//# sourceMappingURL=renderJsonSchemaToMarkdownDoc.js.map

package/lib/tools/renderJsonSchemaToMarkdownDoc.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/tools/renderJsonSchemaToMarkdownDoc.ts"],"sourcesContent":["import type { TObject, TSchema } from '@sinclair/typebox';\n\nexport function renderJsonSchemaToMarkdownDoc(rootSchema: any) {\n  // markdown\n  const out: string[] = [];\n  const all = new Set();\n  const pending: TSchema[] = [];\n\n  const addObject = (o: TSchema) => {\n    if (all.has(o.$id)) {\n      return;\n    }\n    all.add(o.$id);\n    pending.push(o);\n  };\n\n  const writeObjectProps = (T: TObject, { prefix = '' }: { prefix?: string } = {}) => {\n    if (!T?.properties) {\n      return;\n    }\n    for (const [name, schema] of Object.entries(T.properties)) {\n      let typ = schema.$id || schema.type;\n\n      if (typ === 'array') {\n        typ = `${schema.items.$id || schema.items.type}[]`;\n        if (schema.items.$id) {\n          addObject(schema.items);\n        }\n      } else if (schema.$id) {\n        addObject(schema);\n      }\n      if (!typ) {\n        if ('anyOf' in schema) {\n          typ = 'enum';\n        }\n      }\n\n      out.push(`| ${prefix}${name} | ${typ} | ${schema.title || schema.description || ''} |`);\n\n      if (typ === 'object') {\n        writeObjectProps(schema as TObject, { prefix: `${prefix}${name}.` });\n      } else if (schema.type === 'array') {\n        if (schema.items.type === 'object' && !schema.items.$id) {\n          writeObjectProps(schema.items as TObject, { prefix: `${prefix}${name}[].` });\n        }\n      }\n    }\n  };\n  const writeObject = (T: TObject) => {\n    out.push(`### ${T.title || T.$id}`);\n    out.push(`\n| $id | 名字 |\n| --- | --- |\n| ${T.$id || ''} | ${T.title || ''} | \n    `);\n    if (T.description) {\n      out.push('');\n      out.push(`> ${T.description}`);\n      out.push('');\n    }\n\n    out.push(`| 名字 | 类型 | 说明 |`);\n    out.push(`| --- | --- | --- |`);\n\n    writeObjectProps(T);\n\n    out.push('');\n  };\n\n  writeObject(rootSchema);\n\n  for (const schema of pending) {\n    if (schema.type === 'object') {\n      writeObject(schema as TObject);\n    } else if ('anyOf' in schema) {\n      out.push(`### ${schema.$id || schema.title}`);\n      out.push(`\n| $id | 名字 |\n| --- | --- |\n| ${schema.$id || ''} | ${schema.title || ''} | \n    `);\n\n      out.push(`| 值 |  说明 |`);\n      out.push(`| --- | --- |`);\n      for (const item of schema.anyOf) {\n        out.push(`| ${item.const} | ${item.title || item.description || ''} |`);\n      }\n      out.push('');\n    }\n  }\n\n  return out.join('\\n');\n}\n"],"names":["renderJsonSchemaToMarkdownDoc","rootSchema","out","all","Set","pending","addObject","o","has","$id","add","push","writeObjectProps","T","prefix","properties","name","schema","Object","entries","typ","type","items","title","description","writeObject","item","anyOf","const","join"],"mappings":"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"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@wener/common",
+  "version": "1.0.1",
+  "type": "module",
+  "description": "",
+  "author": "",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./lib/index.js"
+    },
+    "./jsonschema": {
+      "types": "./src/jsonschema/index.ts",
+      "default": "./lib/jsonschema/index.js"
+    },
+    "./meta": {
+      "types": "./src/meta/index.ts",
+      "default": "./lib/meta/index.js"
+    },
+    "./password": {
+      "types": "./src/password/index.ts",
+      "default": "./lib/password/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "lib.d.ts",
+    "libs",
+    "src"
+  ],
+  "keywords": [],
+  "dependencies": {
+    "es-toolkit": "^1.27.0",
+    "ts-pattern": "^5.5.0",
+    "@wener/utils": "1.1.51"
+  },
+  "devDependencies": {
+    "@sinclair/typebox": "^0.34.9",
+    "@types/argon2-browser": "^1.18.4",
+    "@types/bcrypt": "^5.0.2",
+    "@types/bcryptjs": "^2.4.6",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "ajv-i18n": "^4.2.0",
+    "ajv-keywords": "^5.1.0",
+    "argon2": "^0.41.1",
+    "argon2-browser": "^1.18.0",
+    "bcrypt": "^5.1.1",
+    "bcryptjs": "^2.4.3"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { normalizePagination } from './normalizePagination';
+export { parseSort, type SortRule } from './parseSort';

package/src/jsonschema/JsonSchema.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+import { JsonSchema } from './JsonSchema';
+
+describe('jsonschema', () => {
+  it('should create from schema', () => {
+    for (const [a, b] of [
+      [{ type: 'string' }, ''],
+      [{ type: 'number' }, 0],
+      [{ type: 'number', default: 1 }, 1],
+      [{ type: 'integer' }, 0],
+      [{ type: 'array' }, []],
+      [{ type: 'object' }, {}],
+      [
+        {
+          type: 'object',
+          properties: {
+            a: { type: 'string' },
+          },
+          required: ['a'],
+        },
+        { a: '' },
+      ],
+    ]) {
+      expect(JsonSchema.create(a)).toEqual(b);
+    }
+  });
+});

package/src/jsonschema/JsonSchema.ts

@@ -0,0 +1,197 @@
+import type { Static, TSchema } from '@sinclair/typebox';
+import Ajv, { type ErrorObject, type Options } from 'ajv';
+import addFormats from 'ajv-formats';
+import localize from 'ajv-i18n/localize/zh';
+import addKeywords from 'ajv-keywords';
+import { isNil } from 'es-toolkit';
+import { match, P } from 'ts-pattern';
+import type { JsonSchemaDef } from './types';
+
+function _createAjv(opt: Options) {
+  const ajv = new Ajv(opt);
+  addKeywords(ajv);
+  addFormats(ajv);
+  return ajv;
+}
+
+type ValidateOptions = {
+  mutate?: boolean;
+  clone?: boolean;
+  ajv?: Ajv;
+};
+
+type ValidateResult<T> =
+  | {
+      data: T;
+      success: true;
+      message: undefined;
+    }
+  | {
+      data: undefined;
+      success: false;
+      message: string;
+      errors: ErrorObject[];
+    };
+
+function validate({
+  schema,
+  data,
+  mutate,
+  clone,
+  ajv,
+}: ValidateOptions & {
+  schema: any;
+  data: any;
+}) {
+  let opts: Options = {
+    // strict: 'log',
+    strict: true,
+    strictSchema: 'log', // skip unknown keywords in schema
+  };
+
+  if (mutate) {
+    Object.assign(opts, {
+      removeAdditional: true,
+      useDefaults: true,
+      coerceTypes: true,
+      allErrors: true,
+    });
+  }
+
+  if (clone) {
+    data = structuredClone(data);
+  }
+
+  if (!ajv) {
+    ajv = JsonSchema.createAjv(opts);
+  }
+
+  const validate = ajv.compile(schema);
+
+  // consider reusing validate instance
+
+  const valid = validate(data);
+  const errors = validate.errors;
+  localize(errors);
+
+  return {
+    data,
+    success: valid,
+    message: ajv.errorsText(errors),
+    errors: errors,
+  };
+}
+
+type TypeOfSchema<S> = S extends TSchema ? Static<S> : any;
+
+export namespace JsonSchema {
+  export let schemas: JsonSchemaDef[] = [];
+
+  export const createAjv = _createAjv;
+
+  export function addSchema(
+    schema: JsonSchemaDef,
+    {
+      onConflict = 'throw',
+    }: {
+      onConflict?: 'throw' | 'ignore' | 'replace' | ((old: JsonSchemaDef, neo: JsonSchemaDef) => JsonSchemaDef);
+    } = {},
+  ) {
+    if (!schema.$id) throw new Error('Schema must have $id');
+    switch (onConflict) {
+      case 'ignore':
+        onConflict = (old) => old;
+        break;
+      case 'replace':
+        onConflict = (_, neo) => neo;
+        break;
+      case 'throw':
+        onConflict = (old, neo) => {
+          throw new Error(`Schema ${neo.$id} already exists`);
+        };
+        break;
+    }
+    let idx = schemas.findIndex((s) => s.$id === schema.$id);
+    if (idx >= 0) {
+      schemas[idx] = onConflict(schemas[idx], schema);
+    } else {
+      schemas.push(schema);
+    }
+  }
+
+  /**
+   * Check data is valid, will not use default
+   */
+  export function check<S>(schema: S, data: any): ValidateResult<TypeOfSchema<S>> {
+    return validate({ schema, data, mutate: false, clone: true }) as any;
+  }
+
+  /**
+   * Parse data with default value and coerceTypes
+   */
+  export function safeParse<S>(schema: S, data: any): ValidateResult<TypeOfSchema<S>> {
+    return validate({ schema, data, mutate: true, clone: true }) as any;
+  }
+
+  export function parse<S>(schema: S, data: any): TypeOfSchema<S> {
+    const { data: out, message, errors } = validate({ schema, data, mutate: true, clone: true });
+    if (errors) {
+      throw new Error(message);
+    }
+    return out;
+  }
+
+  export function create<S>(schema: S, data?: any): TypeOfSchema<S> {
+    // will not ensure value match the rule
+    return match(schema as JsonSchemaDef)
+      .returnType<any>()
+      .with({ const: P.select() }, (v) => v)
+      .with({ default: P.select() }, (v) => v)
+      .with({ anyOf: P.nonNullable }, (schema) => {
+        return create(schema.anyOf[0]);
+      })
+      .with({ oneOf: P.nonNullable }, (schema) => {
+        return create(schema.oneOf[0]);
+      })
+      .with({ type: 'string' }, (schema) => '')
+      .with({ type: P.union('number', 'integer') }, (schema) => 0)
+      .with({ type: 'object' }, (schema) => {
+        let out = validate({ schema, data: data ?? {}, mutate: true });
+        if (!out.success) {
+          // fallback
+          let obj = data || {};
+          schema.required?.forEach((key) => {
+            if (!(key in obj)) {
+              let last = obj[key];
+              let prop = schema.properties?.[key];
+              if (prop && isNil(last)) obj[key] = JsonSchema.create(prop, last);
+            }
+          });
+          out = validate({ schema, data: obj, mutate: true });
+          if (!out.success) {
+            console.warn(`Failed to create object with schema: ${out.message}`);
+          }
+        }
+        return out.data;
+      })
+      .with({ type: 'null' }, () => null)
+      .with({ type: 'boolean' }, (schema) => false)
+      .with({ type: 'array' }, (schema) => [])
+      .otherwise(() => {
+        return undefined;
+      });
+  }
+
+  export function isPrimitiveType(schema: any): boolean {
+    return match(schema as JsonSchemaDef)
+      .returnType<boolean>()
+      .with({ type: P.union('number', 'integer', 'string', 'boolean') }, () => true)
+      .with({ anyOf: P.nonNullable }, (schema) => {
+        return isPrimitiveType(schema.anyOf[0]);
+      })
+      .with({ oneOf: P.nonNullable }, (schema) => {
+        return isPrimitiveType(schema.oneOf[0]);
+      })
+      .otherwise(() => false);
+  }
+}

package/src/jsonschema/index.ts

@@ -0,0 +1,2 @@
+export { JsonSchema } from './JsonSchema';
+export type { JsonSchemaDef } from './types';

package/src/jsonschema/types.d.ts

@@ -0,0 +1,173 @@
+type JsonSchemaTypeName =
+  | 'string' //
+  | 'number'
+  | 'integer'
+  | 'boolean'
+  | 'object'
+  | 'array'
+  | 'null';
+
+type JsonValue =
+  | string //
+  | number
+  | boolean
+  | {
+      [key: string]: JsonValue;
+    }
+  | JsonValue[]
+  | null;
+
+type JsonSchemaVersion =
+  | 'http://json-schema.org/schema' // latest
+  | 'https://json-schema.org/draft/2020-12/schema'
+  // draft-07
+  | 'http://json-schema.org/draft-07/schema#' //
+  | 'http://json-schema.org/draft-07/hyper-schema#';
+
+type JsonSchemaFormatName =
+  //
+  | 'date-time'
+  | 'date'
+  | 'time'
+  | 'duration'
+  //
+  | 'email'
+  | 'idn-email'
+  //
+  | 'hostname'
+  | 'idn-hostname'
+  | 'ipv4'
+  | 'ipv6'
+  //
+  | 'uri'
+  | 'uri-reference'
+  | 'iri'
+  | 'iri-reference'
+  | 'uuid'
+  | 'uri-template'
+  | 'regex'
+  | 'json-pointer'
+  | 'relative-json-pointer';
+
+export type JsonSchemaDef = {
+  $id?: string;
+  $ref?: string;
+  /**
+   * Meta schema
+   *
+   * Recommended values:
+   * - 'http://json-schema.org/schema#'
+   * - 'http://json-schema.org/hyper-schema#'
+   * - 'http://json-schema.org/draft-07/schema#'
+   * - 'http://json-schema.org/draft-07/hyper-schema#'
+   *
+   * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-5
+   */
+  $schema?: JsonSchemaVersion | string;
+  $comment?: string;
+
+  $defs?: {
+    [key: string]: JsonSchemaDef;
+  };
+
+  type?: JsonSchemaTypeName | JsonSchemaTypeName[];
+  enum?: JsonValue[];
+  const?: JsonValue;
+
+  //region Numeric Validation
+
+  multipleOf?: number;
+  maximum?: number;
+  exclusiveMaximum?: number;
+  minimum?: number;
+  exclusiveMinimum?: number;
+
+  //endregion
+
+  //region String Validation
+
+  maxLength?: number;
+  minLength?: number;
+  pattern?: string;
+
+  //endregion
+
+  //region Array Validation
+
+  items?: JsonSchemaDef | JsonSchemaDef[];
+  additionalItems?: JsonSchemaDef;
+  maxItems?: number;
+  minItems?: number;
+  uniqueItems?: boolean;
+  contains?: JsonSchemaDef;
+  //endregion
+
+  //region Object Validation
+
+  maxProperties?: number;
+  minProperties?: number;
+  required?: string[];
+  properties?: {
+    [key: string]: JsonSchemaDef;
+  };
+  patternProperties?: {
+    [key: string]: JsonSchemaDef;
+  };
+  additionalProperties?: JsonSchemaDef;
+  dependencies?: {
+    [key: string]: JsonSchemaDef | string[];
+  };
+  propertyNames?: JsonSchemaDef;
+  //endregion
+
+  //region Conditional
+
+  if?: JsonSchemaDef;
+  then?: JsonSchemaDef;
+  else?: JsonSchemaDef;
+
+  //endregion
+
+  //region Boolean Logic
+
+  allOf?: JsonSchemaDef[];
+  anyOf?: JsonSchemaDef[];
+  oneOf?: JsonSchemaDef[];
+  not?: JsonSchemaDef;
+  //endregion
+
+  //region Semantic
+
+  format?: JsonSchemaFormatName | string;
+
+  //endregion
+
+  //region String-Encoding Non-JSON Data
+
+  contentMediaType?: string;
+  contentEncoding?: string;
+  contentSchema?: JsonSchemaDef;
+  //endregion
+
+  /**
+   * use {@link $defs} instead
+   */
+  definitions?: Record<string, JsonSchemaDef>;
+
+  //region Meta-Data Annotations
+  /**
+   * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-10
+   */
+
+  title?: string;
+  description?: string;
+  default?: JsonValue;
+  readOnly?: boolean;
+  writeOnly?: boolean;
+  examples?: JsonValue;
+  deprecated?: boolean;
+
+  //endregion
+
+  nullable?: boolean;
+};

package/src/meta/defineInit.ts

@@ -0,0 +1,68 @@
+import type { MaybePromise } from '@wener/utils';
+import { startCase } from 'es-toolkit';
+
+type DefineInitOptions = {
+  name: string;
+  title?: string;
+  onInit?: () => any;
+  metadata?: Record<string, any>;
+};
+export type InitDef = {
+  name: string;
+  title: string;
+  onInit?: () => any;
+  metadata: Record<string, any>;
+};
+let _all: InitDef[] = [];
+
+export function defineInit(o: DefineInitOptions) {
+  const def = {
+    title: startCase(o.name),
+    metadata: {},
+    ...o,
+  };
+  let idx = _all.findIndex((v) => v.name === def.name);
+  if (idx >= 0) {
+    console.warn(`skip redefined init: ${def.name}`);
+  } else {
+    _all.push(def);
+  }
+
+  return def;
+}
+
+let result = new Map<any, MaybePromise<InitResult>>();
+
+type InitResult = {
+  name: string;
+  success: boolean;
+  error?: any;
+};
+
+export async function runInit(inits = _all) {
+  for (let init of inits) {
+    if (result.get(init)) {
+      return;
+    }
+    result.set(
+      init,
+      Promise.resolve().then(async () => {
+        let out: InitResult = {
+          name: init.name,
+          success: true,
+        };
+        try {
+          await init.onInit?.();
+        } catch (e) {
+          console.error(`Failed to init ${init.name}`, e);
+          out.success = false;
+          out.error = e;
+        }
+        result.set(init, out);
+        return out;
+      }),
+    );
+  }
+
+  return Promise.all(result.values());
+}

package/src/meta/defineMetadata.test.ts

@@ -0,0 +1,15 @@
+import { expect, test } from 'vitest';
+import { createMetadataKey, defineMetadata, getMetadata } from './defineMetadata';
+
+test('defineMetadata', () => {
+  const key = createMetadataKey<string>('name');
+
+  const user = {
+    metadata: {},
+  };
+
+  defineMetadata(user, key, 'wener');
+
+  expect(user.metadata).toEqual({ name: 'wener' });
+  expect(getMetadata(user, key)).toEqual('wener');
+});

package/src/meta/defineMetadata.ts

@@ -0,0 +1,57 @@
+import { startCase } from 'es-toolkit';
+import { get, set } from 'es-toolkit/compat';
+
+type HasMetadata = {
+  metadata?: Record<string, any>;
+};
+
+type MetadataKey<T> = {
+  key: string;
+  type: T;
+  title: string;
+  description?: string;
+};
+
+interface CreateMetadataKeyOptions {
+  key: string;
+  title?: string;
+  description?: string;
+}
+
+export function createMetadataKey<T = never>(key: string, opts?: Omit<CreateMetadataKeyOptions, 'key'>): MetadataKey<T>;
+export function createMetadataKey<T = never>(opts: CreateMetadataKeyOptions): MetadataKey<T>;
+export function createMetadataKey<T = never>(a: any, b?: any): MetadataKey<T> {
+  const opts: CreateMetadataKeyOptions =
+    typeof a === 'string'
+      ? {
+          key: a,
+          ...b,
+        }
+      : a;
+
+  const { key } = opts;
+  opts.title ||= startCase(key);
+
+  const k: MetadataKey<T> = {
+    ...opts,
+    type: null as any,
+  } as MetadataKey<T>;
+
+  if ('toStringTag' in Symbol && typeof Symbol.toStringTag === 'symbol') {
+    Object.defineProperty(k, Symbol.toStringTag, {
+      value: key,
+    });
+  }
+
+  return k;
+}
+
+export function defineMetadata<T>(res: HasMetadata, key: MetadataKey<T>, opts: T) {
+  res.metadata = res.metadata || {};
+  set(res.metadata, key.key, opts);
+}
+
+export function getMetadata<T>(res: HasMetadata | undefined | null, key: MetadataKey<T>): T | undefined {
+  if (!res?.metadata) return undefined;
+  return get(res.metadata, key.key);
+}