@wener/common 2.0.1 → 2.0.3

package/src/foundation/schema/index.ts

@@ -0,0 +1 @@
+export { SexType, SexTypeSchema } from './SexType';

package/src/foundation/schema/parseSexType.ts

@@ -0,0 +1,19 @@
+import { SexType } from './SexType';
+
+export function parseSexType(s: string | null | undefined): undefined | SexType {
+	if (!s) return undefined;
+
+	switch (s.toLowerCase()) {
+		case '♂':
+		case '男':
+		case 'male':
+		case 'man':
+			return SexType.Male;
+		case '♀':
+		case '女':
+		case 'female':
+		case 'woman':
+			return SexType.Female;
+	}
+	return undefined;
+}

package/src/foundation/schema/types.ts

@@ -0,0 +1,8 @@
+import z from 'zod/v4';
+
+export const CoordinatesSchema = z
+	.object({
+		latitude: z.number().min(-90).max(90).describe('纬度'),
+		longitude: z.number().min(-180).max(180).describe('经度'),
+	})
+	.describe('坐标信息');

package/src/fs/FileSystemError.ts

@@ -0,0 +1,26 @@
+export const FileSystemErrorCode = {
+	ENOENT: 'ENOENT',
+	ENOTDIR: 'ENOTDIR',
+	EEXIST: 'EEXIST',
+	EISDIR: 'EISDIR',
+	ENOTEMPTY: 'ENOTEMPTY',
+	EACCES: 'EACCES',
+	EPERM: 'EPERM',
+	EINVAL: 'EINVAL',
+} as const;
+
+export type FileSystemErrorCode = (typeof FileSystemErrorCode)[keyof typeof FileSystemErrorCode];
+
+export class FileSystemError extends Error {
+	constructor(
+		message: string,
+		public readonly code: FileSystemErrorCode | string,
+	) {
+		super(message);
+		this.name = 'FileSystemError';
+		// Maintains proper stack trace for where our error was thrown (only available on V8)
+		if (Error.captureStackTrace) {
+			Error.captureStackTrace(this, FileSystemError);
+		}
+	}
+}

package/src/fs/IFileSystem.d.ts

@@ -0,0 +1,102 @@
+import type { FileKind, FileUrlOptions } from './types';
+
+// Base operation options
+type OperationOptions = {
+	signal?: AbortSignal;
+};
+
+// Directory operations
+export type ReaddirOptions = OperationOptions & {
+	glob?: string;
+	recursive?: boolean;
+	depth?: number;
+	kind?: FileKind;
+	hidden?: boolean;
+};
+export type MkdirOptions = OperationOptions & {
+	recursive?: boolean;
+};
+// File operations
+export type ReadFileOptions = OperationOptions & {
+	encoding?: 'text' | 'binary';
+	onDownloadProgress?: (e: { loaded: number; total: number }) => void;
+};
+export type WriteFileOptions = OperationOptions & {
+	overwrite?: boolean;
+	onUploadProgress?: (e: { loaded: number; total: number }) => void;
+};
+export type RenameOptions = OperationOptions & {
+	overwrite?: boolean;
+};
+export type RmOptions = OperationOptions & {
+	recursive?: boolean;
+	force?: boolean;
+};
+export type CopyOptions = OperationOptions & {
+	overwrite?: boolean;
+	shallow?: boolean;
+};
+export type CreateReadStreamOptions = OperationOptions & {
+	range?: { start: number; end?: number };
+	signal?: AbortSignal;
+};
+export type CreateWriteStreamOptions = OperationOptions & {
+	overwrite?: boolean;
+};
+export type StatOptions = OperationOptions & {};
+
+type WritableData = string | ArrayBuffer | ArrayBufferView | ReadableStream;
+
+/**
+ * Universal file system interface (browser & server compatible)
+ */
+export type IFileSystem = {
+	readdir(dir: string, options?: ReaddirOptions): Promise<IFileStat[]>;
+	stat(entry: string, options?: StatOptions): Promise<IFileStat>;
+	mkdir(path: string, options?: MkdirOptions): Promise<void>;
+	readFile(path: string, options?: ReadFileOptions & { encoding: 'text' }): Promise<string>;
+	readFile(path: string, options?: ReadFileOptions): Promise<Uint8Array>;
+	writeFile(path: string, data: WritableData, options?: WriteFileOptions): Promise<void>;
+	rm(path: string, options?: RmOptions): Promise<void>;
+	rename(oldPath: string, newPath: string, options?: RenameOptions): Promise<void>;
+	exists(path: string): Promise<boolean>;
+	copy(src: string, dest: string, options?: CopyOptions): Promise<void>;
+
+	getUrl?(path: IFileStat | string, options?: FileUrlOptions): string | undefined;
+
+	createReadableStream?(path: string, options?: CreateReadStreamOptions): ReadableStream;
+	createWritableStream?(path: string, options?: CreateWriteStreamOptions): WritableStream;
+};
+
+/**
+ * Server/Node.js specific file system interface with stream support
+ */
+export type IServerFileSystem = IFileSystem & {
+	createReadStream(path: string, options?: CreateReadStreamOptions): import('node:stream').Readable;
+	createWriteStream(path: string, options?: CreateWriteStreamOptions): import('node:stream').Writable;
+	writeFile(
+		path: string,
+		data: WritableData | Buffer | import('node:stream').Readable,
+		options?: WriteFileOptions,
+	): Promise<void>;
+};
+
+export type IFileStat = {
+	/**
+	 * parent path
+	 */
+	directory: string;
+	/**
+	 * full path
+	 */
+	path: string;
+	/**
+	 * basename
+	 */
+	name: string;
+	kind: 'directory' | 'file';
+	mtime: number;
+	meta: Record<string, any>;
+	size: number;
+};
+

package/src/fs/MemoryFileSystem.test.ts

@@ -0,0 +1,37 @@
+import { beforeEach, describe, test } from 'vitest';
+import { createMemoryFileSystem } from './createMemoryFileSystem';
+import { runFileSystemTest } from './tests/runFileSystemTest';
+
+describe('MemoryFileSystem', () => {
+	let fs: ReturnType<typeof createMemoryFileSystem>;
+
+	beforeEach(() => {
+		fs = createMemoryFileSystem({
+			root: {
+				path: '/',
+				directory: '',
+				name: '',
+				kind: 'directory',
+				meta: {},
+				mtime: Date.now(),
+				size: 0,
+				children: [
+					{
+						path: '/README.txt',
+						directory: '/',
+						name: 'README.txt',
+						kind: 'file',
+						content: 'Hello',
+						size: 5,
+						meta: {},
+						mtime: Date.now(),
+					},
+				],
+			},
+		});
+	});
+
+	test('common tests', async () => {
+		await runFileSystemTest(fs);
+	});
+});

package/src/fs/createBrowserFileSystem.ts

@@ -0,0 +1,291 @@
+import { dirname, join, normalize } from 'pathe';
+import type {
+	CopyOptions,
+	IFileStat,
+	IFileSystem,
+	MkdirOptions,
+	ReaddirOptions,
+	ReadFileOptions,
+	RenameOptions,
+	RmOptions,
+	WriteFileOptions,
+} from './IFileSystem';
+import type { FileUrlOptions } from './types';
+
+class BrowserFSError extends Error {
+	constructor(
+		message: string,
+		public code?: string,
+	) {
+		super(message);
+		this.name = 'BrowserFSError';
+	}
+}
+
+type BrowserFile = IFileStat & {
+	kind: 'file';
+	meta: {
+		handle: FileSystemFileHandle;
+		file: File;
+	};
+};
+
+type BrowserDirectory = IFileStat & {
+	kind: 'directory';
+	meta: {
+		handle: FileSystemDirectoryHandle;
+	};
+};
+
+type BrowserNode = BrowserFile | BrowserDirectory;
+
+/**
+ * Creates an IFileSystem instance backed by the browser's File System Access API.
+ * @param root A FileSystemDirectoryHandle, usually obtained from `window.showDirectoryPicker()`.
+ */
+export function createBrowserFileSystem(root: FileSystemDirectoryHandle): IFileSystem {
+	return new BrowserFS(root);
+}
+
+class BrowserFS implements IFileSystem {
+	root: FileSystemDirectoryHandle;
+	node: BrowserDirectory;
+
+	constructor(root: FileSystemDirectoryHandle) {
+		this.root = root;
+		this.node = {
+			path: '/',
+			name: '',
+			directory: '',
+			kind: 'directory',
+			mtime: 0,
+			size: 0,
+			meta: {
+				handle: root,
+			},
+		};
+	}
+
+	/**
+	 * Resolves a path string to a file or directory handle. This is the core navigation logic.
+	 * @returns A tuple of [handle, parentHandle, name] or [null, parentHandle, name] if not found.
+	 */
+	private async _getHandle(path: string): Promise<[FileSystemHandle | null, FileSystemDirectoryHandle | null, string]> {
+		const normalized = normalize(path);
+		if (normalized === '/' || normalized === '.') {
+			return [this.root, null, this.root.name];
+		}
+
+		const parts = normalized.split('/').filter((p) => p);
+		const name = parts.pop()!;
+
+		let parent: FileSystemDirectoryHandle = this.root;
+		for (const part of parts) {
+			try {
+				parent = await parent.getDirectoryHandle(part);
+			} catch (e: any) {
+				if (e.name === 'NotFoundError' || e.name === 'TypeMismatchError') {
+					return [null, null, name]; // Parent path does not exist or is a file
+				}
+				throw e;
+			}
+		}
+
+		try {
+			// Check for file first, then directory
+			const handle = await parent.getFileHandle(name).catch(() => parent.getDirectoryHandle(name));
+			return [handle, parent, name];
+		} catch (e: any) {
+			if (e.name === 'NotFoundError') {
+				return [null, parent, name]; // Entry not found
+			}
+			throw e;
+		}
+	}
+
+	/**
+	 * Converts a FileSystemHandle into our standard IFileStat object.
+	 */
+	private async _toFileStat(handle: FileSystemHandle, path: string): Promise<IFileStat> {
+		const isFile = handle.kind === 'file';
+		const file = isFile ? await (handle as FileSystemFileHandle).getFile() : undefined;
+
+		return {
+			name: handle.name,
+			kind: handle.kind,
+			path: path,
+			directory: dirname(path),
+			size: file?.size ?? 0,
+			mtime: file?.lastModified ?? Date.now(),
+			meta: { handle, file },
+		};
+	}
+
+	// --- IFileSystem Implementation ---
+
+	async stat(path: string): Promise<IFileStat> {
+		const [handle] = await this._getHandle(path);
+		if (!handle) {
+			throw new BrowserFSError(`Path not found: ${path}`, 'ENOENT');
+		}
+		return this._toFileStat(handle, path);
+	}
+
+	async exists(path: string): Promise<boolean> {
+		const [handle] = await this._getHandle(path);
+		return !!handle;
+	}
+
+	async readdir(dir: string, options?: ReaddirOptions): Promise<IFileStat[]> {
+		const [handle] = await this._getHandle(dir);
+		if (!handle) {
+			throw new BrowserFSError(`Directory not found: ${dir}`, 'ENOENT');
+		}
+		if (handle.kind !== 'directory') {
+			throw new BrowserFSError(`Not a directory: ${dir}`, 'ENOTDIR');
+		}
+
+		const entries: IFileStat[] = [];
+		for await (const entry of (handle as FileSystemDirectoryHandle).values()) {
+			entries.push(await this._toFileStat(entry, join(dir, entry.name)));
+		}
+		return entries;
+	}
+
+	async mkdir(path: string, options: MkdirOptions = {}): Promise<void> {
+		const parts = normalize(path)
+			.split('/')
+			.filter((p) => p);
+		let currentDir = this.root;
+
+		for (const part of parts) {
+			try {
+				currentDir = await currentDir.getDirectoryHandle(part, { create: options.recursive });
+			} catch (e: any) {
+				// If recursive is false, getDirectoryHandle throws if a segment is missing.
+				// We re-throw a more standard error.
+				if (e.name === 'NotFoundError' && !options.recursive) {
+					throw new BrowserFSError(`Cannot create directory: Parent does not exist for path ${path}`, 'ENOENT');
+				}
+				// If it's another error (like a file with the same name), re-throw it.
+				throw e;
+			}
+		}
+	}
+
+	readFile(path: string, options?: ReadFileOptions & { encoding: 'text' }): Promise<string>;
+	readFile(path: string, options?: ReadFileOptions): Promise<Uint8Array>;
+	async readFile(path: string, options?: ReadFileOptions): Promise<string | Uint8Array> {
+		const [handle] = await this._getHandle(path);
+		if (!handle || handle.kind !== 'file') {
+			throw new BrowserFSError(`File not found: ${path}`, 'ENOENT');
+		}
+		const file = await (handle as FileSystemFileHandle).getFile();
+		return options?.encoding === 'text' ? file.text() : file.bytes();
+	}
+
+	async writeFile(path: string, data: any, options: WriteFileOptions = {}): Promise<void> {
+		const { overwrite = true } = options;
+		const [handle, parent, name] = await this._getHandle(path);
+
+		if (!parent) {
+			throw new BrowserFSError(`Parent directory does not exist for path: ${path}`, 'ENOENT');
+		}
+		if (handle && !overwrite) {
+			throw new BrowserFSError(`File already exists: ${path}`, 'EEXIST');
+		}
+
+		const fileHandle = await parent.getFileHandle(name, { create: true });
+		const writable = await fileHandle.createWritable();
+		await writable.write(data);
+		await writable.close();
+	}
+
+	async rm(path: string, options: RmOptions = {}): Promise<void> {
+		const { recursive = false, force = false } = options;
+		const [handle, parent, name] = await this._getHandle(path);
+
+		if (!handle) {
+			if (force) return; // If force is true, do not error on not found.
+			throw new BrowserFSError(`Path not found: ${path}`, 'ENOENT');
+		}
+		if (!parent) {
+			throw new BrowserFSError(`Cannot remove root directory`);
+		}
+
+		await parent.removeEntry(name, { recursive });
+	}
+
+	async rename(oldPath: string, newPath: string, options?: RenameOptions): Promise<void> {
+		// The File System Access API does NOT have a native move/rename.
+		// The standard workaround is to copy, then delete the original.
+		await this.copy(oldPath, newPath, options);
+		await this.rm(oldPath, { recursive: true });
+	}
+
+	async copy(srcPath: string, destPath: string, options?: CopyOptions): Promise<void> {
+		const [srcHandle] = await this._getHandle(srcPath);
+		if (!srcHandle) {
+			throw new BrowserFSError(`Source not found: ${srcPath}`, 'ENOENT');
+		}
+
+		const [destHandle, destParent, destName] = await this._getHandle(destPath);
+		if (!destParent) {
+			throw new BrowserFSError(`Destination directory does not exist: ${dirname(destPath)}`, 'ENOENT');
+		}
+		if (destHandle && !options?.overwrite) {
+			throw new BrowserFSError(`Destination already exists: ${destPath}`, 'EEXIST');
+		}
+		if (destHandle?.kind === 'directory' && srcHandle.kind === 'file') {
+			throw new BrowserFSError(`Cannot overwrite a directory with a file: ${destPath}`, 'EISDIR');
+		}
+
+		await this._copyEntry(srcHandle, destParent, destName);
+	}
+
+	private async _copyEntry(
+		srcHandle: FileSystemHandle,
+		destDirHandle: FileSystemDirectoryHandle,
+		newName: string,
+	): Promise<void> {
+		if (srcHandle.kind === 'file') {
+			const file = await (srcHandle as FileSystemFileHandle).getFile();
+			const destFileHandle = await destDirHandle.getFileHandle(newName, { create: true });
+			const writable = await destFileHandle.createWritable();
+			await writable.write(file);
+			await writable.close();
+		} else if (srcHandle.kind === 'directory') {
+			const newDirHandle = await destDirHandle.getDirectoryHandle(newName, { create: true });
+			for await (const entry of (srcHandle as FileSystemDirectoryHandle).values()) {
+				await this._copyEntry(entry, newDirHandle, entry.name);
+			}
+		}
+	}
+
+	async createUrl(stat: IFileStat, options?: FileUrlOptions): Promise<string> {
+		// The handle is stored in the meta property in our _toFileStat method
+		const handle = stat.meta.handle as FileSystemHandle | undefined;
+		if (handle?.kind !== 'file') {
+			// Return a placeholder or throw an error for directories
+			return '';
+		}
+		const file = await (handle as FileSystemFileHandle).getFile();
+		return URL.createObjectURL(file);
+	}
+
+	createReadStream(): never {
+		throw new Error('Streaming is not implemented for BrowserFS. Use readFile instead.');
+	}
+
+	createWriteStream(): never {
+		throw new Error('Streaming is not implemented for BrowserFS. Use writeFile instead.');
+	}
+
+	createWritableStream(): never {
+		throw new Error('Streaming is not implemented for BrowserFS. Use writeFile instead.');
+	}
+
+	createReadableStream(): never {
+		throw new Error('Streaming is not implemented for BrowserFS. Use readFile instead.');
+	}
+}