@wener/common 2.0.2 → 2.0.3

package/src/dayjs/resolveRelativeTime.test.ts

@@ -0,0 +1,357 @@
+import dayjs from 'dayjs';
+import quarterOfYear from 'dayjs/plugin/quarterOfYear';
+import weekOfYear from 'dayjs/plugin/weekOfYear';
+import { describe, expect, it } from 'vitest';
+import { resolveRelativeTime } from './resolveRelativeTime';
+
+dayjs.extend(quarterOfYear);
+dayjs.extend(weekOfYear);
+
+describe('resolveRelativeTime', () => {
+	const fixedDate = new Date('2024-03-15T14:30:45.123Z');
+
+	describe('basic cases', () => {
+		it('should handle "now"', () => {
+			const result = resolveRelativeTime('now', fixedDate);
+			expect(result).toEqual(fixedDate);
+		});
+
+		it('should handle "now" without reference date', () => {
+			const result = resolveRelativeTime('now', undefined);
+			expect(result).toBeInstanceOf(Date);
+		});
+	});
+
+	describe('subtraction operations', () => {
+		it('should subtract seconds', () => {
+			const result = resolveRelativeTime('now-30s', fixedDate);
+			const expected = dayjs(fixedDate).subtract(30, 'second').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should subtract minutes', () => {
+			const result = resolveRelativeTime('now-15m', fixedDate);
+			const expected = dayjs(fixedDate).subtract(15, 'minute').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should subtract hours', () => {
+			const result = resolveRelativeTime('now-2h', fixedDate);
+			const expected = dayjs(fixedDate).subtract(2, 'hour').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should subtract days', () => {
+			const result = resolveRelativeTime('now-7d', fixedDate);
+			const expected = dayjs(fixedDate).subtract(7, 'day').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should subtract weeks', () => {
+			const result = resolveRelativeTime('now-2w', fixedDate);
+			const expected = dayjs(fixedDate).subtract(2, 'week').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should subtract months', () => {
+			const result = resolveRelativeTime('now-1M', fixedDate);
+			const expected = dayjs(fixedDate).subtract(1, 'month').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should subtract quarters', () => {
+			const result = resolveRelativeTime('now-1Q', fixedDate);
+			const expected = dayjs(fixedDate).subtract(1, 'quarter').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should subtract years', () => {
+			const result = resolveRelativeTime('now-1y', fixedDate);
+			const expected = dayjs(fixedDate).subtract(1, 'year').toDate();
+			expect(result).toEqual(expected);
+		});
+	});
+
+	describe('addition operations', () => {
+		it('should add seconds', () => {
+			const result = resolveRelativeTime('now+30s', fixedDate);
+			const expected = dayjs(fixedDate).add(30, 'second').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should add minutes', () => {
+			const result = resolveRelativeTime('now+15m', fixedDate);
+			const expected = dayjs(fixedDate).add(15, 'minute').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should add hours', () => {
+			const result = resolveRelativeTime('now+3h', fixedDate);
+			const expected = dayjs(fixedDate).add(3, 'hour').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should add days', () => {
+			const result = resolveRelativeTime('now+5d', fixedDate);
+			const expected = dayjs(fixedDate).add(5, 'day').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should add weeks', () => {
+			const result = resolveRelativeTime('now+2w', fixedDate);
+			const expected = dayjs(fixedDate).add(2, 'week').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should add months', () => {
+			const result = resolveRelativeTime('now+2M', fixedDate);
+			const expected = dayjs(fixedDate).add(2, 'month').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should add quarters', () => {
+			const result = resolveRelativeTime('now+1Q', fixedDate);
+			const expected = dayjs(fixedDate).add(1, 'quarter').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should add years', () => {
+			const result = resolveRelativeTime('now+1y', fixedDate);
+			const expected = dayjs(fixedDate).add(1, 'year').toDate();
+			expect(result).toEqual(expected);
+		});
+	});
+
+	describe('truncation operations', () => {
+		it('should truncate to start of second', () => {
+			const result = resolveRelativeTime('now/s', fixedDate);
+			const expected = dayjs(fixedDate).startOf('second').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should truncate to start of minute', () => {
+			const result = resolveRelativeTime('now/m', fixedDate);
+			const expected = dayjs(fixedDate).startOf('minute').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should truncate to start of hour', () => {
+			const result = resolveRelativeTime('now/h', fixedDate);
+			const expected = dayjs(fixedDate).startOf('hour').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should truncate to start of day', () => {
+			const result = resolveRelativeTime('now/d', fixedDate);
+			const expected = dayjs(fixedDate).startOf('day').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should truncate to start of week', () => {
+			const result = resolveRelativeTime('now/w', fixedDate);
+			const expected = dayjs(fixedDate).startOf('week').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should truncate to start of month', () => {
+			const result = resolveRelativeTime('now/M', fixedDate);
+			const expected = dayjs(fixedDate).startOf('month').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should truncate to start of quarter', () => {
+			const result = resolveRelativeTime('now/Q', fixedDate);
+			const expected = dayjs(fixedDate).startOf('quarter').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should truncate to start of year', () => {
+			const result = resolveRelativeTime('now/y', fixedDate);
+			const expected = dayjs(fixedDate).startOf('year').toDate();
+			expect(result).toEqual(expected);
+		});
+	});
+
+	describe('endOf truncation operations (backslash)', () => {
+		it('should truncate to end of second', () => {
+			const result = resolveRelativeTime('now\\s', fixedDate);
+			const expected = dayjs(fixedDate).endOf('second').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should truncate to end of minute', () => {
+			const result = resolveRelativeTime('now\\m', fixedDate);
+			const expected = dayjs(fixedDate).endOf('minute').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should truncate to end of hour', () => {
+			const result = resolveRelativeTime('now\\h', fixedDate);
+			const expected = dayjs(fixedDate).endOf('hour').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should truncate to end of day', () => {
+			const result = resolveRelativeTime('now\\d', fixedDate);
+			const expected = dayjs(fixedDate).endOf('day').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should truncate to end of week', () => {
+			const result = resolveRelativeTime('now\\w', fixedDate);
+			const expected = dayjs(fixedDate).endOf('week').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should truncate to end of month', () => {
+			const result = resolveRelativeTime('now\\M', fixedDate);
+			const expected = dayjs(fixedDate).endOf('month').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should truncate to end of quarter', () => {
+			const result = resolveRelativeTime('now\\Q', fixedDate);
+			const expected = dayjs(fixedDate).endOf('quarter').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should truncate to end of year', () => {
+			const result = resolveRelativeTime('now\\y', fixedDate);
+			const expected = dayjs(fixedDate).endOf('year').toDate();
+			expect(result).toEqual(expected);
+		});
+	});
+
+	describe('complex combinations', () => {
+		it('should handle "now-1M/M" (start of previous month)', () => {
+			const result = resolveRelativeTime('now-1M/M', fixedDate);
+			const expected = dayjs(fixedDate).subtract(1, 'month').startOf('month').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should handle "now/d+1d-1s" (end of current day)', () => {
+			const result = resolveRelativeTime('now/d+1d-1s', fixedDate);
+			const expected = dayjs(fixedDate).startOf('day').add(1, 'day').subtract(1, 'second').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should handle multiple operations "now-1w+2d-3h"', () => {
+			const result = resolveRelativeTime('now-1w+2d-3h', fixedDate);
+			const expected = dayjs(fixedDate).subtract(1, 'week').add(2, 'day').subtract(3, 'hour').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should handle "now-1M\\M" (end of previous month)', () => {
+			const result = resolveRelativeTime('now-1M\\M', fixedDate);
+			const expected = dayjs(fixedDate).subtract(1, 'month').endOf('month').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should handle "now\\d" vs "now/d+1d-1s" (both end of current day)', () => {
+			const resultBackslash = resolveRelativeTime('now\\d', fixedDate);
+			const resultAlternative = resolveRelativeTime('now/d+1d-1s', fixedDate);
+			const expectedBackslash = dayjs(fixedDate).endOf('day').toDate();
+			const expectedAlternative = dayjs(fixedDate).startOf('day').add(1, 'day').subtract(1, 'second').toDate();
+
+			expect(resultBackslash).toEqual(expectedBackslash);
+			expect(resultAlternative).toEqual(expectedAlternative);
+			// Note: endOf gives millisecond precision (.999), while alternative gives second precision (.000)
+			// Both represent end of day, but endOf is more precise
+			expect(resultBackslash.getTime()).toBeGreaterThan(resultAlternative.getTime());
+		});
+
+		it('should handle "now-1y\\y" (end of previous year)', () => {
+			const result = resolveRelativeTime('now-1y\\y', fixedDate);
+			const expected = dayjs(fixedDate).subtract(1, 'year').endOf('year').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should handle "now/y+6M" (middle of current year)', () => {
+			const result = resolveRelativeTime('now/y+6M', fixedDate);
+			const expected = dayjs(fixedDate).startOf('year').add(6, 'month').toDate();
+			expect(result).toEqual(expected);
+		});
+	});
+
+	describe('error cases', () => {
+		it('should throw error for invalid format', () => {
+			expect(() => resolveRelativeTime('invalid', fixedDate)).toThrow('Invalid');
+		});
+
+		it('should throw error for non-now start', () => {
+			expect(() => resolveRelativeTime('then-1h', fixedDate)).toThrow('Invalid');
+		});
+
+		it('should throw error for invalid time unit', () => {
+			expect(() => resolveRelativeTime('now-1x', fixedDate)).toThrow('Invalid time operand');
+		});
+
+		it('should throw error for invalid operator', () => {
+			expect(() => resolveRelativeTime('now*1h', fixedDate)).toThrow('Invalid relative time format');
+		});
+
+		it('should throw error for invalid truncation unit', () => {
+			expect(() => resolveRelativeTime('now/z', fixedDate)).toThrow();
+		});
+
+		it('should throw error for incomplete operation', () => {
+			expect(() => resolveRelativeTime('now-', fixedDate)).toThrow('Invalid relative time format');
+		});
+	});
+
+	describe('Grafana examples from comments', () => {
+		it('should handle "now-24h" (last 24 hours)', () => {
+			const result = resolveRelativeTime('now-24h', fixedDate);
+			const expected = dayjs(fixedDate).subtract(24, 'hour').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should handle "now/M" (start of current month)', () => {
+			const result = resolveRelativeTime('now/M', fixedDate);
+			const expected = dayjs(fixedDate).startOf('month').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should handle "now-7d" (last 7 days)', () => {
+			const result = resolveRelativeTime('now-7d', fixedDate);
+			const expected = dayjs(fixedDate).subtract(7, 'day').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should handle "now/y" (start of current year)', () => {
+			const result = resolveRelativeTime('now/y', fixedDate);
+			const expected = dayjs(fixedDate).startOf('year').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should handle "now/w" (start of current week)', () => {
+			const result = resolveRelativeTime('now/w', fixedDate);
+			const expected = dayjs(fixedDate).startOf('week').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should handle "now\\d" (end of current day)', () => {
+			const result = resolveRelativeTime('now\\d', fixedDate);
+			const expected = dayjs(fixedDate).endOf('day').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should handle "now\\M" (end of current month)', () => {
+			const result = resolveRelativeTime('now\\M', fixedDate);
+			const expected = dayjs(fixedDate).endOf('month').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should handle "now\\w" (end of current week)', () => {
+			const result = resolveRelativeTime('now\\w', fixedDate);
+			const expected = dayjs(fixedDate).endOf('week').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should handle "now\\y" (end of current year)', () => {
+			const result = resolveRelativeTime('now\\y', fixedDate);
+			const expected = dayjs(fixedDate).endOf('year').toDate();
+			expect(result).toEqual(expected);
+		});
+	});
+});

package/src/dayjs/resolveRelativeTime.ts

@@ -0,0 +1,167 @@
+import dayjs from 'dayjs';
+import duration from 'dayjs/plugin/duration';
+import quarterOfYear from 'dayjs/plugin/quarterOfYear';
+import weekOfYear from 'dayjs/plugin/weekOfYear';
+
+dayjs.extend(duration);
+dayjs.extend(quarterOfYear);
+dayjs.extend(weekOfYear);
+
+/**
+ * Resolves a Grafana-style relative time string and returns the corresponding Date.
+ *
+ * @param s - The relative time string to parse (must start with "now")
+ * @param now - Optional reference date. If undefined, uses current time
+ * @returns The calculated Date based on the relative time expression
+ *
+ * @throws {Error} When the format is invalid or contains unsupported operators/units
+ *
+ * ## Syntax
+ *
+ * All expressions must start with `now` followed by optional operations:
+ *
+ * ### Operators
+ * - `-` - Subtraction (e.g., `now-1h` for one hour ago)
+ * - `+` - Addition (e.g., `now+1d` for one day from now)
+ * - `/` - Truncation to beginning of time unit (e.g., `now/d` for start of current day)
+ * - `\` - Truncation to end of time unit (e.g., `now\d` for end of current day)
+ *
+ * ### Time Units
+ * - `s` - seconds
+ * - `m` - minutes
+ * - `h` - hours
+ * - `d` - days
+ * - `w` - weeks
+ * - `M` - months
+ * - `Q` - quarters
+ * - `y` - years
+ *
+ * ### Operations
+ * Operations are processed sequentially from left to right:
+ * - **Addition/Subtraction**: `now±{count}{unit}` (e.g., `now-24h`, `now+1d`)
+ * - **Truncation to start**: `now/{unit}` (e.g., `now/d`, `now/M`)
+ * - **Truncation to end**: `now\{unit}` (e.g., `now\d`, `now\M`)
+ * - **Complex**: Multiple operations can be chained (e.g., `now-1M/M`, `now\d`, `now-1y\y`)
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * resolveRelativeTime('now')           // Current time
+ * resolveRelativeTime('now-1h')        // One hour ago
+ * resolveRelativeTime('now+1d')        // One day from now
+ * resolveRelativeTime('now/d')         // Start of current day
+ * resolveRelativeTime('now\\d')        // End of current day
+ *
+ * // Common patterns
+ * resolveRelativeTime('now-24h')       // Last 24 hours
+ * resolveRelativeTime('now-7d')        // Last 7 days
+ * resolveRelativeTime('now/M')         // Start of current month
+ * resolveRelativeTime('now\\M')        // End of current month
+ * resolveRelativeTime('now-1M/M')      // Start of previous month
+ * resolveRelativeTime('now-1M\\M')     // End of previous month
+ * resolveRelativeTime('now/w')         // Start of current week
+ * resolveRelativeTime('now\\w')        // End of current week
+ * resolveRelativeTime('now/y')         // Start of current year
+ * resolveRelativeTime('now\\y')        // End of current year
+ *
+ * // Complex expressions
+ * resolveRelativeTime('now/d+1d-1s')   // End of current day (alternative method)
+ * resolveRelativeTime('now\\d')        // End of current day (direct method)
+ * resolveRelativeTime('now-1w+2d-3h')  // 1 week ago, plus 2 days, minus 3 hours
+ *
+ * // With reference date
+ * const refDate = new Date('2024-03-15T14:30:45.123Z');
+ * resolveRelativeTime('now-1h', refDate);  // One hour before reference date
+ * resolveRelativeTime('now\\d', refDate);  // End of reference day
+ * ```
+ */
+export function resolveRelativeTime(s: string | Date | number, now?: Date | undefined): Date {
+	{
+		let out: Date | undefined;
+		if (!s) {
+		} else if (s instanceof Date) {
+			out = s;
+		} else if (typeof s === 'number') {
+			out = new Date(s);
+		} else if (!s.startsWith('now')) {
+			out = new Date(s);
+		}
+		if (out) {
+			if (isNaN(out.getTime())) {
+				throw new Error(`Invalid date: ${s}`);
+			}
+			return out;
+		}
+	}
+
+	if (typeof s !== 'string' || !s.startsWith('now')) {
+		throw new Error(`Invalid relative time format: ${s}`);
+	}
+
+	let current = dayjs(now);
+	const remaining = s.slice(3); // Remove 'now'
+
+	if (!remaining) {
+		return current.toDate();
+	}
+
+	// Split by operators while keeping them in the result
+	const parts = remaining.split(/([+\-/\\])/).filter((part) => part !== '');
+
+	for (let i = 0; i < parts.length; i += 2) {
+		const operator = parts[i];
+		const operand = parts[i + 1];
+
+		if (!operator || !operand) {
+			throw new Error(`Invalid relative time format: ${s}`);
+		}
+
+		if (operator === '/') {
+			// Truncation to start operation
+			checkDurationUnit(operand);
+			current = current.startOf(operand);
+		} else if (operator === '\\') {
+			// Truncation to end operation
+			checkDurationUnit(operand);
+			current = current.endOf(operand);
+		} else {
+			// Addition or subtraction operation
+			const match = operand.match(/^(\d+)([smhdwMQy])$/);
+			if (!match) {
+				throw new Error(`Invalid time operand: ${operand}`);
+			}
+
+			const [, amountStr, unit] = match;
+			checkDurationUnit(unit);
+			const amount = parseInt(amountStr, 10);
+
+			if (operator === '+') {
+				current = current.add(amount, unit as 'w');
+			} else if (operator === '-') {
+				current = current.subtract(amount, unit as 'Q');
+			} else {
+				throw new Error(`Invalid operator: ${operator}`);
+			}
+		}
+	}
+
+	return current.toDate();
+}
+
+/** Array of all valid time units */
+export const RelativeDurationUnits = ['ms', 's', 'm', 'h', 'd', 'w', 'M', 'Q', 'y'] as const;
+
+/** Valid time units for relative time expressions */
+export type RelativeDurationUnit = (typeof RelativeDurationUnits)[number];
+
+/**
+ * Type guard to validate and assert that a string is a valid time unit.
+ *
+ * @param u - The string to check
+ * @throws {Error} When the unit is not supported
+ */
+export function checkDurationUnit(u: string): asserts u is RelativeDurationUnit {
+	if (!RelativeDurationUnits.includes(u as RelativeDurationUnit)) {
+		throw new Error(`Invalid unit: ${u}`);
+	}
+}

package/src/emittery/emitter.ts

@@ -0,0 +1,9 @@
+import Emittery, { type EventName } from 'emittery';
+
+export function createEmitter<EventData = Record<EventName, any>>(name: string) {
+	return new Emittery<EventData>({
+		debug: {
+			name,
+		},
+	});
+}

package/src/emittery/index.ts

@@ -0,0 +1 @@
+export { createEmitter } from './emitter';

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