@wener/common 1.0.3 → 1.0.4

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

package/src/jsonschema/JsonSchema.ts

@@ -8,190 +8,158 @@ 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;
+	const ajv = new Ajv(opt);
+	addKeywords(ajv);
+	addFormats(ajv);
+	return ajv;
 }
 
-type ValidateOptions = {
-  mutate?: boolean;
-  clone?: boolean;
-  ajv?: 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,
-  };
+	| { 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);
-  }
+	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);
+	}
 }