@wener/common 2.0.2 → 2.0.5

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 (Number.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

@@ -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: string | undefined;
+		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/TypeSchema.d.ts

@@ -10,23 +10,23 @@ import type { JsonSchemaDef } from '../jsonschema';
 export type TypeSchema<I = unknown, O = I> = TSchema | z.ZodSchema<O, I> | JsonSchemaDef | StandardSchemaV1<I, O>;
 
 export type SchemaOutput<S extends TypeSchema> =
-	S extends StandardSchemaV1<infer I, infer O>
+	S extends StandardSchemaV1<infer _I, infer O>
 		? O
-		: S extends z.ZodSchema<infer O, infer I>
+		: S extends z.ZodSchema<infer O, infer _I>
 			? O
 			: S extends TSchema
 				? TypeBoxStaticEncode<S>
-				: S extends JsonSchemaDef<infer I, infer O>
+				: S extends JsonSchemaDef<infer _I, infer O>
 					? O
 					: never;
 
 export type SchemaInput<S extends TypeSchema> =
-	S extends StandardSchemaV1<infer I, infer O>
+	S extends StandardSchemaV1<infer I, infer _O>
 		? I
-		: S extends z.ZodSchema<infer O, infer I>
+		: S extends z.ZodSchema<infer _O, infer I>
 			? I
 			: S extends TSchema
 				? TypeBoxStaticDecode<S>
-				: S extends JsonSchemaDef<infer I, infer O>
+				: S extends JsonSchemaDef<infer I, infer _O>
 					? I
 					: never;

package/src/schema/createSchemaData.ts

@@ -54,8 +54,8 @@ function _create(schema: JsonSchemaDef, options: CreateOptions, ctx: { required:
 		.with({ oneOf: P.nonNullable }, (schema) => {
 			return _create(schema.oneOf[0], options, { required: false });
 		})
-		.with({ type: 'string' }, (schema) => '')
-		.with({ type: P.union('number', 'integer') }, (schema) => 0)
+		.with({ type: 'string' }, (_schema) => '')
+		.with({ type: P.union('number', 'integer') }, (_schema) => 0)
 		.with({ type: 'object' }, () => {
 			const out: Record<string, any> = {};
 
@@ -73,8 +73,8 @@ function _create(schema: JsonSchemaDef, options: CreateOptions, ctx: { required:
 			return out;
 		})
 		.with({ type: 'null' }, () => null)
-		.with({ type: 'boolean' }, (schema) => false)
-		.with({ type: 'array' }, (schema) => [])
+		.with({ type: 'boolean' }, (_schema) => false)
+		.with({ type: 'array' }, (_schema) => [])
 		.otherwise(() => {
 			return undefined;
 		});

package/src/schema/findJsonSchemaByPath.ts

@@ -14,10 +14,10 @@ export function findJsonSchemaByPath(schema: TypeSchema, objectPath: string) {
 	for (const segment of segments) {
 		// 检查当前 schema 是否是对象类型且有 properties
 		if (
-			currentSchema
-			&& typeof currentSchema === 'object'
-			&& currentSchema.properties
-			&& currentSchema.properties[segment]
+			currentSchema &&
+			typeof currentSchema === 'object' &&
+			currentSchema.properties &&
+			currentSchema.properties[segment]
 		) {
 			currentSchema = currentSchema.properties[segment];
 			continue;