@wener/common 1.0.3 → 1.0.5

package/src/cn/types.d.ts

@@ -5,47 +5,47 @@
  * @see https://en.wikipedia.org/wiki/Foreign_Permanent_Resident_ID_Card
  */
 export interface ResidentIdentityCardInfo {
-  /**
-   * @title 姓名
-   */
-  name: string;
-  /**
-   * @title 性别
-   */
-  sex: 'Male' | 'Female';
-  /**
-   * @title 民族
-   * 例如 '汉'/'满'/'回'
-   */
-  ethnicity: string;
-  /**
-   * @title 出生日期
-   * @format date
-   */
-  birthDate: string;
-  /**
-   * @title 地址
-   *
-   * - 通常为 domicile/户籍地
-   */
-  address: string;
-  /**
-   * @title 身份证号
-   */
-  identityCardNumber: string;
-  /**
-   * @title 签发机关
-   */
-  issuer: string;
-  /**
-   * @title 有效期开始日期
-   * @format date
-   */
-  validStartDate: string;
-  /**
-   * @title 有效期结束日期
-   * @format date
-   * @description 如长期有效则为 空
-   */
-  validEndDate?: string;
+	/**
+	 * @title 姓名
+	 */
+	name: string;
+	/**
+	 * @title 性别
+	 */
+	sex: 'Male' | 'Female';
+	/**
+	 * @title 民族
+	 * 例如 '汉'/'满'/'回'
+	 */
+	ethnicity: string;
+	/**
+	 * @title 出生日期
+	 * @format date
+	 */
+	birthDate: string;
+	/**
+	 * @title 地址
+	 *
+	 * - 通常为 domicile/户籍地
+	 */
+	address: string;
+	/**
+	 * @title 身份证号
+	 */
+	identityCardNumber: string;
+	/**
+	 * @title 签发机关
+	 */
+	issuer: string;
+	/**
+	 * @title 有效期开始日期
+	 * @format date
+	 */
+	validStartDate: string;
+	/**
+	 * @title 有效期结束日期
+	 * @format date
+	 * @description 如长期有效则为 空
+	 */
+	validEndDate?: string;
 }

package/src/consola/createStandardConsolaReporter.ts

@@ -0,0 +1,31 @@
+import type { ConsolaOptions, ConsolaReporter, LogObject } from 'consola/core';
+import { formatLogObject } from './formatLogObject';
+
+type Formatter = (
+	o: LogObject,
+	ctx: {
+		options: ConsolaOptions;
+	},
+) => string;
+
+export function createStandardConsolaReporter({
+	format = formatLogObject,
+}: {
+	format?: Formatter;
+} = {}): ConsolaReporter {
+	return {
+		log: (o, ctx) => {
+			let out = format(o, ctx);
+			let fn = console.log;
+
+			const { level } = o;
+			if (level < 1) {
+				fn = console.error;
+			} else if (level === 1) {
+				fn = console.warn;
+			}
+
+			fn(out);
+		},
+	};
+}

package/src/consola/formatLogObject.ts

@@ -0,0 +1,171 @@
+import colors from 'chalk';
+import type { ConsolaOptions, FormatOptions, LogObject, LogType } from 'consola/core';
+import dayjs from 'dayjs';
+import { isDevelopment } from 'std-env';
+
+const levelColors: Record<LogType, (str: string) => string> = {
+	trace: colors.gray,
+	debug: colors.cyan,
+	info: colors.blueBright,
+	warn: colors.yellow,
+	error: colors.red,
+	fatal: colors.bgRed.white,
+	silent: colors.white,
+	log: colors.white,
+	success: colors.green,
+	fail: colors.red,
+	ready: colors.green,
+	start: colors.cyan,
+	box: colors.white,
+	verbose: colors.green,
+};
+
+const levelShort: Record<LogType, string> = {
+	trace: 'TRAC',
+	debug: 'DEBG',
+	info: 'INFO',
+	warn: 'WARN',
+	error: 'ERRO',
+	fatal: 'FATL',
+	silent: 'SLNT',
+	log: 'LOG ', // Added space to make it 4 characters
+	success: 'SUCC',
+	fail: 'FAIL',
+	ready: 'READ',
+	start: 'STRT',
+	box: 'BOX ', // Added space to make it 4 characters
+	verbose: 'VERB',
+};
+const start = Date.now();
+
+export function formatLogObject(
+	o: LogObject,
+	ctx: {
+		options: ConsolaOptions;
+	},
+) {
+	let { date, type, tag } = o;
+	type = type === 'log' ? 'info' : type;
+
+	const color = levelColors[type] || colors.white;
+	const levelText = levelShort[type] || type.toUpperCase().slice(0, 4); // Get first 4 chars, consistent uppercase
+
+	let line = '';
+	let out: string[] = [];
+
+	// Timestamp
+	if (isDevelopment) {
+		// process.hrtime.bigint()
+		let diff = (date.getTime() - start) / 1000;
+
+		out.push(colors.gray(diff.toFixed(3).padStart(7, ' ')));
+	} else {
+		out.push(colors.gray(dayjs(date).format('YYYY-MM-DD HH:mm:ss.SSS')));
+	}
+
+	// Log Level (colored)
+	// Pad to 4 characters
+	out.push(color(levelText.padEnd(4, ' ')));
+
+	if (tag) {
+		out.push(colors.yellow(`[${tag}]`)); // Added color for tag
+	}
+
+	{
+		const [message, ...additional] = formatArgs(o.args, ctx).split('\n');
+
+		out.push(characterFormat(message));
+
+		line = out.join(' ');
+		if (additional.length > 0) {
+			line += characterFormat(additional.join('\n'));
+		}
+
+		if (type === 'trace') {
+			const _err = new Error('Trace: ' + o.message);
+			line += formatStack(_err.stack || '', _err.message);
+		}
+	}
+
+	// if (!message && typeof args[0] === 'string') {
+	//   message = args.shift();
+	// }
+	// if (message) {
+	//   out.push(message);
+	// }
+	// if (args.length) {
+	//   out.push(...args.map((a) => (typeof a === 'string' ? a : JSON.stringify(a)))); // Handle non-string args
+	// }
+
+	// todo format error
+	// https://github.com/unjs/consola/blob/main/src/reporters/fancy.ts
+
+	// return out.join('  '); // Increased spacing for better readability
+	return line;
+}
+
+function characterFormat(str: string) {
+	return (
+		str
+			// highlight backticks
+			.replace(/`([^`]+)`/gm, (_, m) => colors.cyan(m))
+			// underline underscores
+			.replace(/\s+_([^_]+)_\s+/gm, (_, m) => ` ${colors.underline(m)} `)
+	);
+}
+
+function parseStack(stack: string, message: string) {
+	// const cwd = process.cwd() + sep;
+
+	const lines = stack
+		.split('\n')
+		.splice(message.split('\n').length)
+		.map(
+			(l) => l.trim().replace('file://', ''),
+			// .replace(cwd, '')
+		);
+
+	return lines;
+}
+
+function formatStack(stack: string, message: string, opts?: FormatOptions) {
+	const indent = '  '.repeat((opts?.errorLevel || 0) + 1);
+	return (
+		`\n${indent}`
+		+ parseStack(stack, message)
+			.map(
+				(line) =>
+					'  ' + line.replace(/^at +/, (m) => colors.gray(m)).replace(/\((.+)\)/, (_, m) => `(${colors.cyan(m)})`),
+			)
+			.join(`\n${indent}`)
+	);
+}
+
+function formatArgs(args: any[], opts: FormatOptions) {
+	const _args = args.map((arg) => {
+		if (arg && typeof arg.stack === 'string') {
+			return formatError(arg, opts);
+		}
+		return arg;
+	});
+
+	// Only supported with Node >= 10
+	// https://nodejs.org/api/util.html#util_util_inspect_object_options
+	return formatWithOptions(opts, ..._args);
+}
+
+function formatWithOptions(o: any, ...params: any[]) {
+	// import { formatWithOptions } from 'node:util';
+	return params.join(' ');
+}
+
+function formatError(err: any, opts: FormatOptions): string {
+	const message = err.message ?? formatWithOptions(opts, err);
+	const stack = err.stack ? formatStack(err.stack, message, opts) : '';
+
+	const level = opts?.errorLevel || 0;
+	const causedPrefix = level > 0 ? `${'  '.repeat(level)}[cause]: ` : '';
+	const causedError = err.cause ? '\n\n' + formatError(err.cause, { ...opts, errorLevel: level + 1 }) : '';
+
+	return causedPrefix + message + '\n' + stack + causedError;
+}

package/src/consola/index.ts

@@ -0,0 +1,2 @@
+export { formatLogObject } from './formatLogObject';
+export { createStandardConsolaReporter } from './createStandardConsolaReporter';

package/src/data/formatSort.test.ts

@@ -0,0 +1,13 @@
+import { expect, test } from 'vitest';
+import { formatSort } from './formatSort';
+
+test('formatSort', () => {
+	expect(formatSort([{ field: 'name', order: 'asc' }])).toEqual(['name asc']);
+	expect(formatSort([{ field: 'age', order: 'desc', nulls: 'last' }])).toEqual(['age desc nulls last']);
+	expect(
+		formatSort([
+			{ field: 'name', order: 'asc' },
+			{ field: 'age', order: 'desc' },
+		]),
+	).toEqual(['name asc', 'age desc']);
+});

package/src/data/formatSort.ts

@@ -0,0 +1,18 @@
+import type { SortRule } from './parseSort';
+
+export function formatSort(s: SortRule[]): string[] {
+	return s
+		.map(({ field, order, nulls }) => {
+			if (!field) return '';
+
+			let r = field;
+			if (order) {
+				r += ` ${order}`;
+			}
+			if (nulls) {
+				r += ` nulls ${nulls}`;
+			}
+			return r;
+		})
+		.filter(Boolean);
+}

package/src/data/index.ts

@@ -0,0 +1,5 @@
+export type * from './types';
+
+export { resolvePagination, type PaginationInput, type ResolvedPagination } from './resolvePagination';
+export { parseSort, type SortRule } from './parseSort';
+export { formatSort } from './formatSort';

package/src/data/maybeNumber.ts

@@ -0,0 +1,23 @@
+export type MaybeNumber = number | null | string | undefined | bigint;
+
+export function maybeNumber(v: MaybeNumber) {
+	if (v === null || v === undefined) {
+		return undefined;
+	}
+
+	switch (typeof v) {
+		case 'number':
+			return v;
+		case 'bigint':
+			return Number(v);
+		case 'string':
+			if (v === '') {
+				return undefined;
+			}
+	}
+	const n = Number(v);
+	if (isNaN(n)) {
+		return undefined;
+	}
+	return n;
+}

package/src/data/parseSort.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, test } from 'vitest';
+import { formatSort } from './formatSort';
+import { parseSort } from './parseSort';
+
+describe('parseSort', () => {
+	describe('basic parsing', () => {
+		test('handles empty inputs', () => {
+			expect(parseSort('')).toEqual([]);
+			expect(parseSort([])).toEqual([]);
+			expect(parseSort(null)).toEqual([]);
+			expect(parseSort(undefined)).toEqual([]);
+		});
+
+		test('handles simple field names', () => {
+			expect(parseSort('a')).toEqual([{ field: 'a', order: 'asc' }]);
+			expect(parseSort(['a'])).toEqual([{ field: 'a', order: 'asc' }]);
+			expect(parseSort('a.b')).toEqual([{ field: 'a.b', order: 'asc' }]);
+		});
+
+		test('handles prefix notation', () => {
+			expect(parseSort('-a')).toEqual([{ field: 'a', order: 'desc' }]);
+			expect(parseSort('+b')).toEqual([{ field: 'b', order: 'asc' }]);
+			expect(parseSort('-a,+b')).toEqual([
+				{ field: 'a', order: 'desc' },
+				{ field: 'b', order: 'asc' },
+			]);
+		});
+	});
+
+	describe('explicit ordering', () => {
+		test('handles explicit order keywords', () => {
+			expect(parseSort('a asc')).toEqual([{ field: 'a', order: 'asc' }]);
+			expect(parseSort('a desc')).toEqual([{ field: 'a', order: 'desc' }]);
+			expect(parseSort('-a asc')).toEqual([{ field: 'a', order: 'asc' }]); // explicit order overrides prefix
+		});
+	});
+
+	describe('nulls handling', () => {
+		test('handles nulls specification', () => {
+			expect(parseSort('a asc nulls last')).toEqual([{ field: 'a', order: 'asc', nulls: 'last' }]);
+			expect(parseSort('a asc nulls first')).toEqual([{ field: 'a', order: 'asc', nulls: 'first' }]);
+			expect(parseSort('a desc nulls last')).toEqual([{ field: 'a', order: 'desc', nulls: 'last' }]);
+			expect(parseSort('a nulls first')).toEqual([{ field: 'a', order: 'asc', nulls: 'first' }]);
+			expect(parseSort('-a nulls first')).toEqual([{ field: 'a', order: 'desc', nulls: 'first' }]);
+
+			// Alternative syntax
+			expect(parseSort('a asc last')).toEqual([{ field: 'a', order: 'asc', nulls: 'last' }]);
+		});
+	});
+
+	describe('object notation', () => {
+		test('handles object input', () => {
+			expect(parseSort([{ field: 'a', order: 'asc' }])).toEqual([{ field: 'a', order: 'asc' }]);
+			expect(parseSort([{ field: 'a', order: 'asc', nulls: 'last' }])).toEqual([
+				{ field: 'a', order: 'asc', nulls: 'last' },
+			]);
+		});
+	});
+
+	describe('invalid inputs', () => {
+		test('handles invalid inputs gracefully', () => {
+			expect(parseSort([{ order: 'asc' }])).toEqual([]);
+			expect(parseSort(['a,,', { field: '', order: 'asc' }])).toEqual([{ field: 'a', order: 'asc' }]);
+			expect(parseSort([',,', { field: 'a', order: 'asc' }])).toEqual([{ field: 'a', order: 'asc' }]);
+		});
+	});
+});

package/src/data/parseSort.ts

@@ -0,0 +1,108 @@
+import { arrayOfMaybeArray, type MaybeArray } from '@wener/utils';
+
+export type SortRule = { field: string; order: 'asc' | 'desc'; nulls?: 'last' | 'first' };
+
+/**
+ * Parses various format of sort specifications into standardized SortRule objects
+ *
+ * Supported formats:
+ * - "field asc|desc"
+ * - "field asc|desc nulls first|last"
+ * - "+field" for ascending, "-field" for descending
+ * - Object notation: { field: string, order?: string, nulls?: string }
+ *
+ * @example
+ * parseSort('name desc')               // [{ field: 'name', order: 'desc' }]
+ * parseSort('+name,-age')              // [{ field: 'name', order: 'asc' }, { field: 'age', order: 'desc' }]
+ * parseSort('name asc nulls last')     // [{ field: 'name', order: 'asc', nulls: 'last' }]
+ * parseSort([{ field: 'name' }])       // [{ field: 'name', order: 'asc' }]
+ */
+export function parseSort(
+	order: MaybeArray<{ field?: string; order?: string; nulls?: string } | string> | undefined | null,
+): SortRule[] {
+	if (!order) {
+		return [];
+	}
+
+	return arrayOfMaybeArray(order).flatMap((v): MaybeArray<SortRule> => {
+		if (!v) return [];
+		if (typeof v === 'object') {
+			if (!v.field) {
+				return [];
+			}
+			const rule: SortRule = {
+				field: v.field,
+				order: normalizeOrder(v.order),
+			};
+
+			if (v.nulls) {
+				rule.nulls = normalizeNulls(v.nulls);
+			}
+			return rule;
+		}
+		return v
+			.split(',')
+			.map((v) => v.trim())
+			.filter(Boolean)
+			.map(_parse);
+	});
+}
+
+/**
+ * Normalizes order values to 'asc' or 'desc'
+ */
+function normalizeOrder(order?: string): SortRule['order'] {
+	return order?.toLowerCase() === 'asc' ? 'asc' : 'desc';
+}
+
+/**
+ * Normalizes nulls values to 'last' or 'first'
+ */
+function normalizeNulls(nulls?: string): SortRule['nulls'] {
+	return nulls?.toLowerCase() === 'last' ? 'last' : 'first';
+}
+
+function _parse(v: string): SortRule {
+	const sp = v.split(/\s+/);
+	let field = '';
+	let order: SortRule['order'];
+	let nulls: SortRule['nulls'];
+
+	// Handle first token which should be the field name (possibly with +/- prefix)
+	const f = sp.shift();
+	if (!f) return { field: '', order: 'asc' }; // Defensive programming
+
+	if (f.startsWith('-') || f.startsWith('+')) {
+		field = f.slice(1).trim();
+		order = f.startsWith('-') ? 'desc' : 'asc';
+	} else {
+		field = f.trim();
+	}
+
+	// Process remaining tokens
+	while (sp.length > 0) {
+		const token = sp.shift()?.trim()?.toLowerCase();
+		if (!token) continue;
+
+		switch (token) {
+			case 'asc':
+			case 'desc':
+				order = token;
+				break;
+
+			case 'nulls':
+				nulls = sp.shift()?.trim()?.toLowerCase() === 'last' ? 'last' : 'first';
+				break;
+
+			case 'last':
+			case 'first':
+				nulls = token;
+				break;
+		}
+	}
+
+	order ||= 'asc';
+
+	// Only include nulls if specified
+	return nulls ? { field, order, nulls } : { field, order };
+}

package/src/data/resolvePagination.test.ts

@@ -0,0 +1,58 @@
+import { expect, test } from 'vitest';
+import { resolvePagination } from './resolvePagination';
+
+test(resolvePagination.name, () => {
+	const testCases: Array<[string, any, any]> = [
+		[
+			'pageSize with null pageIndex',
+			{ pageSize: '10', pageIndex: null },
+			{ limit: 10, offset: 0, pageSize: 10, pageNumber: 1, pageIndex: 0 },
+		],
+		[
+			'pageSize with pageIndex',
+			{ pageSize: '10', pageIndex: 1 },
+			{ limit: 10, offset: 10, pageSize: 10, pageNumber: 2, pageIndex: 1 },
+		],
+		[
+			'pageSize with pageIndex 2',
+			{ pageSize: '10', pageIndex: 2 },
+			{ limit: 10, offset: 20, pageSize: 10, pageNumber: 3, pageIndex: 2 },
+		],
+		[
+			'limit with null offset',
+			{ limit: '10', offset: null },
+			{ limit: 10, offset: 0, pageSize: 10, pageNumber: 1, pageIndex: 0 },
+		],
+		[
+			'limit with offset',
+			{ limit: '10', offset: '20' },
+			{ limit: 10, offset: 20, pageSize: 10, pageNumber: 3, pageIndex: 2 },
+		],
+		[
+			'null limit with offset',
+			{ limit: null, offset: '20' },
+			{ limit: 20, offset: 20, pageSize: 20, pageNumber: 2, pageIndex: 1 },
+		],
+		['empty input', {}, { limit: 20, offset: 0, pageSize: 20, pageNumber: 1, pageIndex: 0 }],
+		[
+			'negative values',
+			{ pageSize: '-5', pageIndex: '-1', limit: '-10', offset: '-20' },
+			{ limit: 1, offset: 0, pageSize: 1, pageNumber: 1, pageIndex: 0 },
+		],
+		[
+			'custom pageNumber',
+			{ pageNumber: 3, pageSize: 15 },
+			{ limit: 15, offset: 30, pageSize: 15, pageNumber: 3, pageIndex: 2 },
+		],
+	];
+
+	for (const [description, input, expected] of testCases) {
+		const result = resolvePagination(input);
+		expect(result, description).toMatchObject(expected);
+	}
+});
+
+test(`${resolvePagination.name} with options`, () => {
+	expect(resolvePagination({ pageSize: '200' }, { maxPageSize: 50 })).toMatchObject({ pageSize: 50, limit: 50 });
+	expect(resolvePagination({}, { pageSize: 30 })).toMatchObject({ pageSize: 30, limit: 30 });
+});

package/src/data/resolvePagination.ts

@@ -0,0 +1,60 @@
+import { maybeFunction, type MaybeFunction } from '@wener/utils';
+import { clamp, mapValues, omitBy, pick } from 'es-toolkit';
+import { maybeNumber, type MaybeNumber } from './maybeNumber';
+
+export type PaginationInput = {
+	limit?: MaybeNumber;
+	offset?: MaybeNumber;
+	pageSize?: MaybeNumber;
+	pageNumber?: MaybeNumber;
+	pageIndex?: MaybeNumber;
+};
+
+export type ResolvedPagination = {
+	limit: number;
+	offset: number;
+	pageSize: number;
+	pageNumber: number;
+	pageIndex: number;
+};
+
+export function resolvePagination(
+	page: PaginationInput,
+	options: {
+		pageSize?: MaybeFunction<number, [number | undefined]>;
+		maxPageSize?: number;
+	} = {},
+): ResolvedPagination {
+	let out = omitBy(
+		mapValues(
+			//
+			pick(page, ['limit', 'offset', 'pageSize', 'pageNumber', 'pageIndex']),
+			// to Number
+			(v) => maybeNumber(v),
+		),
+		(v) => v === undefined || v === null,
+	);
+	let { pageSize } = out;
+	if (options.pageSize) {
+		pageSize = maybeFunction(options.pageSize, pageSize);
+	}
+	pageSize ??= 20;
+	pageSize = clamp(pageSize, 1, options.maxPageSize ?? 1000);
+
+	let { pageNumber = 1, pageIndex, limit, offset } = out;
+	// page index over page number
+	pageNumber = Math.max(pageNumber, 1);
+	pageIndex = Math.max(pageIndex ?? pageNumber - 1, 0);
+	limit = Math.max(1, limit ?? pageSize);
+	offset = Math.max(0, offset ?? pageSize * pageIndex);
+
+	pageSize = limit;
+	pageIndex = Math.floor(offset / pageSize);
+	return {
+		limit,
+		offset,
+		pageSize,
+		pageNumber: pageIndex + 1,
+		pageIndex,
+	};
+}

package/src/data/types.d.ts

@@ -0,0 +1,33 @@
+export type ListQueryInput = {
+	/** Filter string */
+	filter?: string;
+	/** Filter array */
+	filters?: string[];
+	/** Filter by IDs */
+	ids?: string[];
+	/** Search query */
+	search?: string;
+	/** Items per page */
+	limit?: number;
+	/** Offset for pagination */
+	offset?: number;
+	/** Ordering criteria */
+	order?: string[];
+	/** Page index (0-based) */
+	pageIndex?: number;
+	/** Page number (1-based) */
+	pageNumber?: number;
+	/** Items per page */
+	pageSize?: number;
+	/** Cursor for pagination */
+	cursor?: string;
+	/** Whether to include deleted items */
+	deleted?: boolean;
+};
+
+type ListResult<T = any> = {
+	/** List of items */
+	data: T[];
+	/** Total number of items */
+	total: number;
+};