@wener/common 2.0.1 → 2.0.3

package/src/s3/formatS3Url.ts

@@ -0,0 +1,84 @@
+import type { ParsedS3Options } from './parseS3Url';
+
+function isValidBucketName(bucket: string): boolean {
+	const bucketRegex = /^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/;
+	return bucketRegex.test(bucket) && !bucket.includes('..') && !bucket.includes('.-') && !bucket.includes('-.');
+}
+
+export function formatS3Url(
+	o: ParsedS3Options,
+	{
+		credentials,
+		useParams,
+	}: {
+		credentials?: boolean;
+		useParams?: boolean;
+	} = {},
+): string {
+	if (!o || typeof o !== 'object') {
+		throw new Error('S3 options must be an object');
+	}
+
+	if (!o.endpoint) {
+		throw new Error('Endpoint is required');
+	}
+
+	let url: URL;
+	let ep = o.endpoint || 's3.amazonaws.com';
+	try {
+		if (URL.canParse(ep)) {
+			url = new URL(ep);
+		} else {
+			url = new URL(`https://${ep}`);
+		}
+	} catch (error) {
+		throw new Error(`Invalid endpoint: ${ep}`);
+	}
+
+	const { useSsl = true, region, pathStyle, port, accessKeyId, secretAccessKey, bucket } = o;
+	url.protocol = useSsl ? 'https:' : 'http:';
+
+	if (credentials) {
+		if (accessKeyId && secretAccessKey) {
+			url.username = encodeURIComponent(accessKeyId);
+			url.password = encodeURIComponent(secretAccessKey);
+		} else {
+			throw new Error('Access Key ID and Secret Access Key are required for credentials');
+		}
+	}
+
+	if (useParams) {
+		if (region) {
+			url.searchParams.set('region', region);
+		}
+		if (pathStyle !== undefined) {
+			url.searchParams.set('pathStyle', String(pathStyle));
+		}
+	}
+
+	if (port) {
+		const portNum = Number(port);
+		if (isNaN(portNum) || portNum < 1 || portNum > 65535) {
+			throw new Error('Port must be a valid number between 1 and 65535');
+		}
+		url.port = String(portNum);
+	}
+
+	if (bucket) {
+		if (!isValidBucketName(bucket)) {
+			throw new Error(`Invalid bucket name: ${bucket}`);
+		}
+
+		if (pathStyle) {
+			url.pathname = `/${bucket}${url.pathname}`;
+		} else {
+			// Check if bucket is already in hostname (virtual-hosted style)
+			const bucketPattern = new RegExp(`^${bucket.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\.`);
+			if (!bucketPattern.test(url.hostname)) {
+				url.hostname = `${bucket}.${url.hostname}`;
+			}
+		}
+	}
+
+	return url.toString();
+}

package/src/s3/index.ts

@@ -0,0 +1,2 @@
+export { parseS3Url, type ParseS3UrlOptions } from './parseS3Url';
+export { formatS3Url } from './formatS3Url';

package/src/s3/parseS3Url.test.ts

@@ -0,0 +1,258 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { parseS3Url } from './parseS3Url';
+
+describe('parseS3Url', () => {
+	beforeEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it('should return undefined for empty URL', () => {
+		const result = parseS3Url({ url: '' });
+		expect(result).toBeUndefined();
+	});
+
+	it('should return undefined for undefined URL', () => {
+		const result = parseS3Url({ url: undefined });
+		expect(result).toBeUndefined();
+	});
+
+	it('should parse basic HTTPS URL', () => {
+		const result = parseS3Url({ url: 'https://s3.amazonaws.com/bucket-name' });
+		expect(result).toEqual({
+			accessKeyId: undefined,
+			secretAccessKey: undefined,
+			endpoint: 's3.amazonaws.com',
+			port: 443,
+			useSsl: true,
+			region: undefined,
+			pathStyle: true,
+			bucket: 'bucket-name',
+		});
+	});
+
+	it('should parse basic HTTP URL', () => {
+		const result = parseS3Url({ url: 'http://s3.amazonaws.com/bucket-name' });
+		expect(result).toEqual({
+			accessKeyId: undefined,
+			secretAccessKey: undefined,
+			endpoint: 's3.amazonaws.com',
+			port: 80,
+			useSsl: false,
+			region: undefined,
+			pathStyle: true,
+			bucket: 'bucket-name',
+		});
+	});
+
+	it('should parse S3 protocol URL', () => {
+		const result = parseS3Url({ url: 's3://s3.amazonaws.com/bucket-name' });
+		expect(result).toEqual({
+			accessKeyId: undefined,
+			secretAccessKey: undefined,
+			endpoint: 's3.amazonaws.com',
+			port: 443,
+			useSsl: true,
+			region: undefined,
+			pathStyle: true,
+			bucket: 'bucket-name',
+		});
+	});
+
+	it('should parse URL with credentials', () => {
+		const result = parseS3Url({ url: 'https://user:pass@s3.amazonaws.com/bucket-name' });
+		expect(result).toEqual({
+			accessKeyId: 'user',
+			secretAccessKey: 'pass',
+			endpoint: 's3.amazonaws.com',
+			port: 443,
+			useSsl: true,
+			region: undefined,
+			pathStyle: true,
+			bucket: 'bucket-name',
+		});
+	});
+
+	it('should parse URL with port', () => {
+		const result = parseS3Url({ url: 'https://s3.amazonaws.com:9000/bucket-name' });
+		expect(result).toEqual({
+			accessKeyId: undefined,
+			secretAccessKey: undefined,
+			endpoint: 's3.amazonaws.com',
+			port: 9000,
+			useSsl: true,
+			region: undefined,
+			pathStyle: true,
+			bucket: 'bucket-name',
+		});
+	});
+
+	it('should parse URL with region query parameter', () => {
+		const result = parseS3Url({ url: 'https://s3.amazonaws.com/bucket-name?region=us-east-1' });
+		expect(result).toEqual({
+			accessKeyId: undefined,
+			secretAccessKey: undefined,
+			endpoint: 's3.amazonaws.com',
+			port: 443,
+			useSsl: true,
+			region: 'us-east-1',
+			pathStyle: true,
+			bucket: 'bucket-name',
+		});
+	});
+
+	it('should parse URL with pathStyle parameter', () => {
+		const result = parseS3Url({ url: 'https://s3.amazonaws.com/bucket-name?pathStyle=true' });
+		expect(result).toEqual({
+			accessKeyId: undefined,
+			secretAccessKey: undefined,
+			endpoint: 's3.amazonaws.com',
+			port: 443,
+			useSsl: true,
+			region: undefined,
+			pathStyle: true,
+			bucket: 'bucket-name',
+		});
+	});
+
+	it('should parse URL with pathStyle=false parameter', () => {
+		const result = parseS3Url({ url: 'https://s3.amazonaws.com/bucket-name?pathStyle=false' });
+		expect(result).toEqual({
+			accessKeyId: undefined,
+			secretAccessKey: undefined,
+			endpoint: 's3.amazonaws.com',
+			port: 443,
+			useSsl: true,
+			region: undefined,
+			pathStyle: false,
+			bucket: 'bucket-name',
+		});
+	});
+
+	it('should detect path style for IP addresses', () => {
+		const result = parseS3Url({ url: 'https://192.168.1.1/bucket-name' });
+		expect(result).toEqual({
+			accessKeyId: undefined,
+			secretAccessKey: undefined,
+			endpoint: '192.168.1.1',
+			port: 443,
+			useSsl: true,
+			region: undefined,
+			pathStyle: true,
+			bucket: 'bucket-name',
+		});
+	});
+
+	it('should detect path style for IPv6 addresses', () => {
+		const result = parseS3Url({ url: 'https://[2001:db8::1]/bucket-name' });
+		expect(result).toEqual({
+			accessKeyId: undefined,
+			secretAccessKey: undefined,
+			endpoint: '[2001:db8::1]',
+			port: 443,
+			useSsl: true,
+			region: undefined,
+			pathStyle: true,
+			bucket: 'bucket-name',
+		});
+	});
+
+	it('should parse AWS virtual hosted style URL', () => {
+		const result = parseS3Url({ url: 'https://my-bucket.s3.us-east-1.amazonaws.com' });
+		expect(result).toEqual({
+			accessKeyId: undefined,
+			secretAccessKey: undefined,
+			endpoint: 'my-bucket.s3.us-east-1.amazonaws.com',
+			port: 443,
+			useSsl: true,
+			region: 'us-east-1',
+			pathStyle: false,
+			bucket: 'my-bucket',
+		});
+	});
+
+	it('should parse AWS virtual hosted style URL with custom endpoint', () => {
+		const result = parseS3Url({ url: 'https://my-bucket.s3.amazonaws.com' });
+		expect(result).toEqual({
+			accessKeyId: undefined,
+			secretAccessKey: undefined,
+			endpoint: 'my-bucket.s3.amazonaws.com',
+			port: 443,
+			useSsl: true,
+			region: undefined,
+			pathStyle: false,
+			bucket: 'my-bucket',
+		});
+	});
+
+	it('should override parameters with provided options', () => {
+		const result = parseS3Url({
+			url: 'https://s3.amazonaws.com/bucket-name',
+			region: 'us-west-2',
+			pathStyle: false,
+		});
+		expect(result).toEqual({
+			accessKeyId: undefined,
+			secretAccessKey: undefined,
+			endpoint: 's3.amazonaws.com',
+			port: 443,
+			useSsl: true,
+			region: 'us-west-2',
+			pathStyle: false,
+			bucket: 'bucket-name',
+		});
+	});
+
+	it('should use S3_URL environment variable by default', () => {
+		vi.stubEnv('S3_URL', 'https://env-bucket.s3.amazonaws.com');
+		const result = parseS3Url();
+		expect(result).toEqual({
+			accessKeyId: undefined,
+			secretAccessKey: undefined,
+			endpoint: 'env-bucket.s3.amazonaws.com',
+			port: 443,
+			useSsl: true,
+			region: undefined,
+			pathStyle: false,
+			bucket: 'env-bucket',
+		});
+	});
+
+	it('should throw error for invalid URL', () => {
+		expect(() => parseS3Url({ url: 'invalid-url' })).toThrow('Invalid S3 URL: invalid-url');
+	});
+
+	it('should handle complex URL with multiple parameters', () => {
+		const result = parseS3Url({
+			url: 'https://user:pass@custom-s3.com:9000/my-bucket?region=us-east-1&pathStyle=true',
+		});
+		expect(result).toEqual({
+			accessKeyId: 'user',
+			secretAccessKey: 'pass',
+			endpoint: 'custom-s3.com',
+			port: 9000,
+			useSsl: true,
+			region: 'us-east-1',
+			pathStyle: true,
+			bucket: 'my-bucket',
+		});
+	});
+
+	it('should ignore undefined and null values in rest parameters', () => {
+		const result = parseS3Url({
+			url: 'https://s3.amazonaws.com/bucket-name',
+			region: 'us-west-2',
+			port: undefined,
+			useSsl: null as any,
+		});
+		expect(result).toEqual({
+			accessKeyId: undefined,
+			secretAccessKey: undefined,
+			endpoint: 's3.amazonaws.com',
+			port: 443,
+			useSsl: true,
+			region: 'us-west-2',
+			pathStyle: true,
+			bucket: 'bucket-name',
+		});
+	});
+});

package/src/s3/parseS3Url.ts

@@ -0,0 +1,88 @@
+import { parseBoolean } from '@wener/utils';
+
+export type ParsedS3Options = {
+	accessKeyId?: string;
+	secretAccessKey?: string;
+	region?: string;
+	useSsl?: boolean;
+	bucket?: string;
+	endpoint: string;
+	port?: number;
+	pathStyle?: boolean;
+	url?: string;
+};
+
+export type ParseS3UrlOptions = Partial<ParsedS3Options>;
+
+function isValidIpAddress(hostname: string): boolean {
+	const ipv4Regex = /^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$/;
+	const ipv6Regex = /^\[([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}]$/;
+	return ipv4Regex.test(hostname) || ipv6Regex.test(hostname);
+}
+
+export function parseS3Url({ url = process.env.S3_URL, ...rest }: ParseS3UrlOptions = {}): ParsedS3Options | undefined {
+	if (!url) return undefined;
+
+	const normalizedUrl = url.startsWith('s3://') ? url.replace(/^s3:\/\//, 'https://') : url;
+	let parsed: URL;
+	try {
+		parsed = new URL(normalizedUrl);
+	} catch (error) {
+		throw new Error(`Invalid S3 URL: ${url}`);
+	}
+
+	const pathStyleParam = parsed.searchParams.get('pathStyle');
+	let pathStyle: boolean | undefined = rest.pathStyle;
+	pathStyle ??= parseBoolean(pathStyleParam, true);
+
+	// Auto-detect path style for IP addresses
+	if (pathStyle === undefined && isValidIpAddress(parsed.hostname)) {
+		pathStyle = true;
+	}
+
+	const result: ParsedS3Options = {
+		accessKeyId: parsed.username || undefined,
+		secretAccessKey: parsed.password || undefined,
+		endpoint: parsed.hostname,
+		port: parsed.port ? Number(parsed.port) : undefined,
+		useSsl: parsed.protocol === 'https:',
+		region: parsed.searchParams.get('region') || undefined,
+		pathStyle,
+	};
+
+	if (!result.port) {
+		if (result.useSsl) {
+			result.port = 443;
+		} else {
+			result.port = 80;
+		}
+	}
+
+	const pathSegments = parsed.pathname.split('/').filter(Boolean);
+	const awsVirtualHostMatch = parsed.hostname.match(/^(.*?)\.s3[.-]([a-z0-9-]+)?\.?amazonaws\.com$/);
+
+	if (result.pathStyle) {
+		result.bucket = pathSegments[0];
+	} else if (awsVirtualHostMatch) {
+		result.bucket = awsVirtualHostMatch[1];
+		result.endpoint = parsed.hostname;
+		if (!result.region && awsVirtualHostMatch[2]) {
+			result.region = awsVirtualHostMatch[2];
+		}
+		result.pathStyle = false;
+	} else {
+		result.bucket = pathSegments[0];
+		if (result.pathStyle === undefined) {
+			result.pathStyle = true;
+		}
+	}
+
+	// Type-safe property assignment
+	for (const [key, value] of Object.entries(rest)) {
+		if (value !== undefined && value !== null && key in result) {
+			(result as Record<string, unknown>)[key] = value;
+		}
+	}
+
+	return result;
+}

package/src/schema/SchemaRegistry.ts

@@ -0,0 +1,48 @@
+import { getGlobalStates } from '@wener/utils';
+import type { JsonSchemaDef } from '../jsonschema';
+import { toJsonSchema, type SchemaOutput, type TypeSchema } from './index';
+
+export namespace SchemaRegistry {
+	const types = getGlobalStates('@wener/common/resource/schema/SchemaRegistry', () => new Map<string, JsonSchemaDef>());
+
+	export function get(name: string): JsonSchemaDef;
+	export function get<S extends TypeSchema>(schema: S): JsonSchemaDef<SchemaOutput<S>>;
+	export function get(needle: TypeSchema | string) {
+		let key = getKey(needle);
+		let found = types.get(key);
+		if (found) {
+			return found;
+		} else {
+			if (needle && typeof needle !== 'string') {
+				return toJsonSchema(needle);
+			}
+		}
+		throw new Error(`Schema not found: ${key}`);
+	}
+
+	function getKey(s: TypeSchema | string) {
+		let key;
+		if (typeof s === 'string') {
+			key = s;
+		} else {
+			let js = toJsonSchema(s);
+			key = js.$id || js.title;
+		}
+		if (!key) {
+			throw new Error(`Schema must have $id or title`);
+		}
+		return key;
+	}
+
+	export function set(key: TypeSchema | string, def: TypeSchema): void;
+	export function set(key: TypeSchema, def?: TypeSchema): void;
+	export function set(key: TypeSchema | string, def?: TypeSchema) {
+		if (!def) {
+			def = key as TypeSchema;
+			if (!def || typeof def !== 'object') {
+				throw new Error(`Invalid schema definition for: ${getKey(key)}`);
+			}
+		}
+		types.set(getKey(key), toJsonSchema(def));
+	}
+}

package/src/schema/createSchemaData.ts

@@ -59,7 +59,7 @@ function _create(schema: JsonSchemaDef, options: CreateOptions, ctx: { required:
 		.with({ type: 'object' }, () => {
 			const out: Record<string, any> = {};
 
-			let required = schema.required || [];
+			let required = Array.isArray(schema.required) ? schema.required : [];
 			for (const [k, v] of Object.entries(schema.properties || {}) as [string, JsonSchemaDef][]) {
 				const value = _create(v, options, {
 					required: required.includes(k),

package/src/schema/formatZodError.test.ts

@@ -0,0 +1,196 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod/v4';
+import { formatZodError } from './formatZodError';
+
+describe('formatZodError', () => {
+	it('should format invalid_type error', () => {
+		const schema = z.object({
+			name: z.string(),
+			age: z.number(),
+		});
+
+		const result = schema.safeParse({ name: 123, age: 'not-a-number' });
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			const formatted = formatZodError(result.error);
+			expect(formatted).toContain('name');
+			expect(formatted).toContain('age');
+		}
+	});
+
+	it('should format required field error', () => {
+		const schema = z.object({
+			name: z.string(),
+			email: z.string().email(),
+		});
+
+		const result = schema.safeParse({});
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			const formatted = formatZodError(result.error);
+			expect(formatted).toContain('必填');
+		}
+	});
+
+	it('should format email validation error', () => {
+		const schema = z.object({
+			email: z.string().email(),
+		});
+
+		const result = schema.safeParse({ email: 'invalid-email' });
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			const formatted = formatZodError(result.error);
+			expect(formatted).toContain('请输入有效的邮箱地址');
+		}
+	});
+
+	it('should format URL validation error', () => {
+		const schema = z.object({
+			url: z.string().url(),
+		});
+
+		const result = schema.safeParse({ url: 'not-a-url' });
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			const formatted = formatZodError(result.error);
+			expect(formatted).toContain('请输入有效的 URL');
+		}
+	});
+
+	it('should format too_small error for string', () => {
+		const schema = z.object({
+			name: z.string().min(5),
+		});
+
+		const result = schema.safeParse({ name: 'abc' });
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			const formatted = formatZodError(result.error);
+			expect(formatted).toContain('至少需要');
+		}
+	});
+
+	it('should format too_small error for number', () => {
+		const schema = z.object({
+			age: z.number().min(18),
+		});
+
+		const result = schema.safeParse({ age: 16 });
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			const formatted = formatZodError(result.error);
+			expect(formatted).toContain('至少需要 18');
+		}
+	});
+
+	it('should format too_big error for string', () => {
+		const schema = z.object({
+			name: z.string().max(10),
+		});
+
+		const result = schema.safeParse({ name: 'this is too long' });
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			const formatted = formatZodError(result.error);
+			expect(formatted).toContain('最多 10 个字符');
+		}
+	});
+
+	it('should format invalid_enum_value error', () => {
+		const schema = z.object({
+			status: z.enum(['active', 'inactive', 'pending']),
+		});
+
+		const result = schema.safeParse({ status: 'invalid' });
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			const formatted = formatZodError(result.error);
+			expect(formatted).toContain('必须是以下值之一');
+		}
+	});
+
+	it('should format invalid_literal error', () => {
+		const schema = z.object({
+			type: z.literal('user'),
+		});
+
+		const result = schema.safeParse({ type: 'admin' });
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			const formatted = formatZodError(result.error);
+			expect(formatted).toContain('必须是 user');
+		}
+	});
+
+	it('should format nested object errors', () => {
+		const schema = z.object({
+			user: z.object({
+				name: z.string(),
+				email: z.string().email(),
+			}),
+		});
+
+		const result = schema.safeParse({
+			user: {
+				name: '',
+				email: 'invalid',
+			},
+		});
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			const formatted = formatZodError(result.error);
+			expect(formatted).toContain('user');
+			expect(formatted).toContain('email');
+		}
+	});
+
+	it('should format array errors', () => {
+		const schema = z.object({
+			tags: z.array(z.string()).min(1),
+		});
+
+		const result = schema.safeParse({ tags: [] });
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			const formatted = formatZodError(result.error);
+			expect(formatted).toContain('至少需要 1 项');
+		}
+	});
+
+	it('should format multiple errors', () => {
+		const schema = z.object({
+			name: z.string().min(1),
+			email: z.string().email(),
+			age: z.number().min(18),
+		});
+
+		const result = schema.safeParse({
+			name: '',
+			email: 'invalid',
+			age: 15,
+		});
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			const formatted = formatZodError(result.error);
+			// Should contain multiple error messages separated by '；'
+			const parts = formatted.split('；');
+			expect(parts.length).toBeGreaterThan(1);
+		}
+	});
+
+	it('should use schema description when available', () => {
+		const schema = z.object({
+			name: z.string().describe('姓名'),
+			email: z.string().email().describe('邮箱地址'),
+		});
+
+		const result = schema.safeParse({ name: '', email: 'invalid' });
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			const formatted = formatZodError(result.error, schema);
+			expect(formatted).toContain('姓名');
+			expect(formatted).toContain('邮箱地址');
+		}
+	});
+});