@wener/common 1.0.2 → 1.0.4

package/src/cn/__snapshots__/ResidentIdentityCardNumber.test.ts.snap

@@ -0,0 +1,15 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`ResidentIdentityCardNumber > should parse 1`] = `
+{
+  "age": 76,
+  "birthDate": "19491231",
+  "checksum": "X",
+  "division": "110105",
+  "female": true,
+  "male": false,
+  "sequence": 2,
+  "sex": "Female",
+  "valid": true,
+}
+`;

package/src/cn/__snapshots__/UnifiedSocialCreditCode.test.ts.snap

@@ -0,0 +1,41 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`UnifiedSocialCreditCode > should parse 1`] = `
+{
+  "bureau": "9",
+  "checksum": "P",
+  "codes": [
+    "9",
+    "1",
+    "330106",
+    "673959654",
+  ],
+  "division": "330106",
+  "labels": [
+    "工商",
+    "企业",
+  ],
+  "subject": "673959654",
+  "subjectType": "1",
+}
+`;
+
+exports[`UnifiedSocialCreditCode > should parse 2`] = `
+{
+  "bureau": "9",
+  "checksum": "R",
+  "codes": [
+    "9",
+    "1",
+    "330106",
+    "MA2CFLDG4",
+  ],
+  "division": "330106",
+  "labels": [
+    "工商",
+    "企业",
+  ],
+  "subject": "MA2CFLDG4",
+  "subjectType": "1",
+}
+`;

package/src/cn/formatDate.ts

@@ -0,0 +1,12 @@
+export function formatDate(date: Date, format: 'yyyyMMDD') {
+	switch (format) {
+		case 'yyyyMMDD': {
+			const year = date.getFullYear();
+			const month = (date.getMonth() + 1).toString().padStart(2, '0');
+			const day = date.getDate().toString().padStart(2, '0');
+			return `${year}${month}${day}`;
+		}
+		default:
+			throw new Error(`Invalid format`);
+	}
+}

package/src/cn/index.ts

@@ -0,0 +1,3 @@
+export { ResidentIdentityCardNumber } from './ResidentIdentityCardNumber';
+export { DivisionCode } from './DivisionCode';
+export { UnifiedSocialCreditCode } from './UnifiedSocialCreditCode';

package/src/cn/parseSex.ts

@@ -0,0 +1,13 @@
+export function parseSex(s: string): undefined | { sex: 'Male' | 'Female'; male: boolean; female: boolean } {
+	if (!s) return undefined;
+
+	switch (s.toLowerCase()) {
+		case '男':
+		case 'male':
+			return { sex: 'Male', male: true, female: false };
+		case '女':
+		case 'female':
+			return { sex: 'Female', male: false, female: true };
+	}
+	return undefined;
+}

package/src/cn/types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 居民身份证
+ *
+ * @see https://en.wikipedia.org/wiki/Resident_Identity_Card
+ * @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;
+}

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 ?? 100);
+
+	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;
+};

package/src/index.ts

@@ -1,2 +1,8 @@
-export { normalizePagination } from './normalizePagination';
-export { parseSort, type SortRule } from './parseSort';
+/**
+ * @deprecated
+ */
+export { parseSort, type SortRule } from './data/parseSort';
+/**
+ * @deprecated
+ */
+export { resolvePagination as normalizePagination } from './data/resolvePagination';

package/src/jsonschema/JsonSchema.test.ts

@@ -2,26 +2,17 @@ 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);
-    }
-  });
+	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);
+		}
+	});
 });