@wener/common 2.0.2 → 2.0.3

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

@@ -2,45 +2,47 @@ import { getGlobalStates } from '@wener/utils';
 import type { JsonSchemaDef } from '../jsonschema';
 import { toJsonSchema, type SchemaOutput, type TypeSchema } from './index';
 
-const types = getGlobalStates('@wener/common/resource/schema/SchemaRegistry', () => new Map<string, JsonSchemaDef>());
+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);
+	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}`);
 	}
-	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`);
+	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;
 	}
-	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)}`);
+	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));
 	}
-	types.set(getKey(key), toJsonSchema(def));
 }

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('邮箱地址');
+		}
+	});
+});