@warlock.js/core 4.0.174 → 4.1.2

package/esm/storage/drivers/do-spaces-driver.d.mts

@@ -0,0 +1,47 @@
+import { CloudStorageDriverOptions } from "../types.mjs";
+import { CloudDriver } from "./cloud-driver.mjs";
+
+//#region ../../@warlock.js/core/src/storage/drivers/do-spaces-driver.d.ts
+/**
+ * DigitalOcean Spaces Storage Driver
+ *
+ * Spaces is S3-compatible with a different URL structure.
+ *
+ * URL Patterns:
+ * - With urlPrefix: {urlPrefix}/{key}
+ * - CDN URL: https://{bucket}.{region}.cdn.digitaloceanspaces.com/{key}
+ * - Origin URL: https://{bucket}.{region}.digitaloceanspaces.com/{key}
+ *
+ * Regions: nyc3, sfo3, ams3, sgp1, fra1, etc.
+ *
+ * @example
+ * ```typescript
+ * const driver = new DOSpacesDriver({
+ *   bucket: "my-space",
+ *   region: "nyc3",
+ *   accessKeyId: process.env.DO_SPACES_KEY,
+ *   secretAccessKey: process.env.DO_SPACES_SECRET,
+ * });
+ * ```
+ */
+declare class DOSpacesDriver extends CloudDriver<CloudStorageDriverOptions> {
+  /**
+   * Driver name
+   */
+  readonly name = "spaces";
+  /**
+   * Get Spaces endpoint URL
+   *
+   * Spaces endpoint format: https://{region}.digitaloceanspaces.com
+   */
+  protected getEndpoint(): string;
+  /**
+   * Get public URL for file
+   *
+   * Note: DO Spaces includes automatic CDN with the `.cdn.` subdomain
+   */
+  url(location: string): string;
+}
+//#endregion
+export { DOSpacesDriver };
+//# sourceMappingURL=do-spaces-driver.d.mts.map

package/esm/storage/drivers/do-spaces-driver.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"do-spaces-driver.d.mts","names":[],"sources":["../../../../../../../@warlock.js/core/src/storage/drivers/do-spaces-driver.ts"],"mappings":";;;;;;AA0BA;;;;;;;;;;;AAoB6B;;;;;;;;;cApBhB,cAAA,SAAuB,WAAW,CAAC,yBAAA;;;;WAI9B,IAAA;;;;;;YAON,WAAA,CAAA;;;;;;EASH,GAAA,CAAI,QAAA;AAAA"}

package/esm/storage/drivers/do-spaces-driver.mjs

@@ -0,0 +1,53 @@
+import { CloudDriver } from "./cloud-driver.mjs";
+import { ltrim } from "@mongez/reinforcements";
+
+//#region ../../@warlock.js/core/src/storage/drivers/do-spaces-driver.ts
+/**
+* DigitalOcean Spaces Storage Driver
+*
+* Spaces is S3-compatible with a different URL structure.
+*
+* URL Patterns:
+* - With urlPrefix: {urlPrefix}/{key}
+* - CDN URL: https://{bucket}.{region}.cdn.digitaloceanspaces.com/{key}
+* - Origin URL: https://{bucket}.{region}.digitaloceanspaces.com/{key}
+*
+* Regions: nyc3, sfo3, ams3, sgp1, fra1, etc.
+*
+* @example
+* ```typescript
+* const driver = new DOSpacesDriver({
+*   bucket: "my-space",
+*   region: "nyc3",
+*   accessKeyId: process.env.DO_SPACES_KEY,
+*   secretAccessKey: process.env.DO_SPACES_SECRET,
+* });
+* ```
+*/
+var DOSpacesDriver = class extends CloudDriver {
+	constructor(..._args) {
+		super(..._args);
+		this.name = "spaces";
+	}
+	/**
+	* Get Spaces endpoint URL
+	*
+	* Spaces endpoint format: https://{region}.digitaloceanspaces.com
+	*/
+	getEndpoint() {
+		return this.options.endpoint || `https://${this.options.region}.digitaloceanspaces.com`;
+	}
+	/**
+	* Get public URL for file
+	*
+	* Note: DO Spaces includes automatic CDN with the `.cdn.` subdomain
+	*/
+	url(location) {
+		if (this.options.urlPrefix) location = `${this.options.urlPrefix.replace(/\/+$/, "")}/${ltrim(location, "/")}`;
+		return `https://${this.options.bucket}.${this.options.region}.cdn.digitaloceanspaces.com/${location}`;
+	}
+};
+
+//#endregion
+export { DOSpacesDriver };
+//# sourceMappingURL=do-spaces-driver.mjs.map

package/esm/storage/drivers/do-spaces-driver.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"do-spaces-driver.mjs","names":[],"sources":["../../../../../../../@warlock.js/core/src/storage/drivers/do-spaces-driver.ts"],"sourcesContent":["import { ltrim } from \"@mongez/reinforcements\";\nimport type { CloudStorageDriverOptions } from \"../types\";\nimport { CloudDriver } from \"./cloud-driver\";\n\n/**\n * DigitalOcean Spaces Storage Driver\n *\n * Spaces is S3-compatible with a different URL structure.\n *\n * URL Patterns:\n * - With urlPrefix: {urlPrefix}/{key}\n * - CDN URL: https://{bucket}.{region}.cdn.digitaloceanspaces.com/{key}\n * - Origin URL: https://{bucket}.{region}.digitaloceanspaces.com/{key}\n *\n * Regions: nyc3, sfo3, ams3, sgp1, fra1, etc.\n *\n * @example\n * ```typescript\n * const driver = new DOSpacesDriver({\n *   bucket: \"my-space\",\n *   region: \"nyc3\",\n *   accessKeyId: process.env.DO_SPACES_KEY,\n *   secretAccessKey: process.env.DO_SPACES_SECRET,\n * });\n * ```\n */\nexport class DOSpacesDriver extends CloudDriver<CloudStorageDriverOptions> {\n  /**\n   * Driver name\n   */\n  public readonly name = \"spaces\";\n\n  /**\n   * Get Spaces endpoint URL\n   *\n   * Spaces endpoint format: https://{region}.digitaloceanspaces.com\n   */\n  protected getEndpoint(): string {\n    return this.options.endpoint || `https://${this.options.region}.digitaloceanspaces.com`;\n  }\n\n  /**\n   * Get public URL for file\n   *\n   * Note: DO Spaces includes automatic CDN with the `.cdn.` subdomain\n   */\n  public url(location: string): string {\n    // 1. Use urlPrefix if configured\n    if (this.options.urlPrefix) {\n      const prefix = this.options.urlPrefix.replace(/\\/+$/, \"\");\n      location = `${prefix}/${ltrim(location, \"/\")}`;\n    }\n\n    // 2. Default Spaces CDN URL\n    return `https://${this.options.bucket}.${this.options.region}.cdn.digitaloceanspaces.com/${location}`;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,IAAa,iBAAb,cAAoC,YAAuC;;;cAIlD;;;;;;;CAOvB,AAAU,cAAsB;EAC9B,OAAO,KAAK,QAAQ,YAAY,WAAW,KAAK,QAAQ,OAAO;CACjE;;;;;;CAOA,AAAO,IAAI,UAA0B;EAEnC,IAAI,KAAK,QAAQ,WAEf,WAAW,GADI,KAAK,QAAQ,UAAU,QAAQ,QAAQ,EACnC,EAAE,GAAG,MAAM,UAAU,GAAG;EAI7C,OAAO,WAAW,KAAK,QAAQ,OAAO,GAAG,KAAK,QAAQ,OAAO,8BAA8B;CAC7F;AACF"}

package/esm/storage/drivers/local-driver.d.mts

@@ -0,0 +1,157 @@
+import { DeleteManyResult, ListOptions, LocalStorageDriverOptions, PutOptions, StorageDriverContract, StorageDriverType, StorageFileData, StorageFileInfo, TemporaryTokenValidation } from "../types.mjs";
+import { UploadedFile } from "../../http/uploaded-file.mjs";
+import { Readable } from "stream";
+
+//#region ../../@warlock.js/core/src/storage/drivers/local-driver.d.ts
+/**
+ * Local filesystem storage driver
+ *
+ * Stores files on the local filesystem with support for:
+ * - File operations (put, get, delete, copy, move)
+ * - Stream operations for large files
+ * - Batch operations
+ * - Signed temporary URLs
+ */
+declare class LocalDriver implements StorageDriverContract {
+  options: LocalStorageDriverOptions;
+  /**
+   * Driver name
+   */
+  readonly name: StorageDriverType;
+  /**
+   * Root path for storage
+   */
+  protected root: string;
+  /**
+   * URL prefix for file URLs
+   */
+  protected urlPrefix: string;
+  /**
+   * URL prefix for temporary file URLs
+   */
+  protected temporaryUrlPrefix: string;
+  /**
+   * Secret key for signing temporary URLs
+   */
+  protected signatureKey?: string;
+  /**
+   * Cached Storage File Metadata
+   */
+  protected _metadata: Map<string, StorageFileInfo>;
+  constructor(options?: LocalStorageDriverOptions);
+  /**
+   * Apply prefix to location path
+   *
+   * Priority: context prefix > driver options prefix > no prefix
+   * This allows multi-tenant scenarios where context overrides driver config.
+   *
+   * @param location - Original location path
+   * @returns Location with prefix applied if one exists
+   */
+  applyPrefix(location: string): string;
+  /**
+   * Put file to local storage
+   */
+  put(file: Buffer | string | UploadedFile, location: string, options?: PutOptions): Promise<StorageFileData>;
+  /**
+   * Put file from a readable stream (for large files)
+   */
+  putStream(stream: Readable, location: string, options?: PutOptions): Promise<StorageFileData>;
+  /**
+   * Get file contents as Buffer
+   */
+  get(location: string): Promise<Buffer>;
+  /**
+   * Get file as a readable stream (for large files)
+   */
+  getStream(location: string): Promise<Readable>;
+  /**
+   * Delete a file
+   */
+  delete(location: string): Promise<boolean>;
+  /**
+   * Delete multiple files at once
+   */
+  deleteMany(locations: string[]): Promise<DeleteManyResult[]>;
+  /**
+   * Delete directory
+   */
+  deleteDirectory(directoryPath: string): Promise<boolean>;
+  /**
+   * Check if file exists
+   */
+  exists(location: string): Promise<boolean>;
+  /**
+   * Get public URL for file
+   */
+  url(location: string): string;
+  /**
+   * Get a temporary signed URL that expires
+   * Returns a clean URL with encoded token: {temporaryUrlPrefix}/{token}
+   *
+   * @param location - File path
+   * @param expiresIn - Seconds until expiration (default: 3600)
+   */
+  temporaryUrl(location: string, expiresIn?: number): Promise<string>;
+  /**
+   * Encode a temporary token containing path, expiry, and signature
+   *
+   * @param location - File path
+   * @param expiresIn - Seconds until expiration
+   */
+  encodeTemporaryToken(location: string, expiresIn: number): string;
+  /**
+   * Validate a temporary URL token
+   * Returns a result object with validation status, file info, and convenience methods
+   *
+   * @param token - The token from the URL
+   */
+  validateTemporaryToken(token: string): Promise<TemporaryTokenValidation>;
+  /**
+   * Get file info/metadata without downloading
+   */
+  metadata(location: string): Promise<StorageFileInfo>;
+  /**
+   * Get file size in bytes (shortcut for metadata().size)
+   */
+  size(location: string): Promise<number>;
+  /**
+   * Copy file to a new location
+   */
+  copy(from: string, to: string): Promise<StorageFileData>;
+  /**
+   * Move file to a new location
+   */
+  move(from: string, to: string): Promise<StorageFileData>;
+  /**
+   * List files in a directory
+   */
+  list(directory: string, options?: ListOptions): Promise<StorageFileInfo[]>;
+  /**
+   * Get absolute filesystem path for a location
+   */
+  path(location: string): string;
+  /**
+   * Get the storage root directory
+   */
+  getRoot(): string;
+  /**
+   * Get absolute file path
+   */
+  protected getAbsolutePath(location: string): string;
+  /**
+   * Convert various input types to Buffer
+   */
+  protected toBuffer(file: Buffer | string | UploadedFile): Promise<Buffer>;
+  /**
+   * Calculate SHA-256 hash
+   */
+  protected calculateHash(buffer: Buffer): string;
+  /**
+   * Guess MIME type from file extension
+   */
+  protected guessMimeType(location: string): string;
+}
+//#endregion
+export { LocalDriver };
+//# sourceMappingURL=local-driver.d.mts.map

package/esm/storage/drivers/local-driver.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-driver.d.mts","names":[],"sources":["../../../../../../../@warlock.js/core/src/storage/drivers/local-driver.ts"],"mappings":";;;;;;;;AAyCA;;;;;;cAAa,WAAA,YAAuB,qBAAA;EA+BR,OAAA,EAAS,yBAAA;EAgD3B;;;EAAA,SA3EQ,IAAA,EAAM,iBAAA;EA8EnB;;;EAAA,UAzEO,IAAA;EAuGP;;;EAAA,UAlGO,SAAA;EA2IgC;;;EAAA,UAtIhC,kBAAA;EAuLwC;;;EAAA,UAlLxC,YAAA;EA4P0C;;;EAAA,UAvP1C,SAAA,EAAS,GAAA,SAAA,eAAA;cAEO,OAAA,GAAS,yBAAA;EA0WU;;;;;;;;;EAtVtC,WAAA,CAAY,QAAA;EAuea;;;EA5cnB,GAAA,CACX,IAAA,EAAM,MAAA,YAAkB,YAAA,EACxB,QAAA,UACA,OAAA,GAAU,UAAA,GACT,OAAA,CAAQ,eAAA;EAlFuB;;;EA4GrB,SAAA,CACX,MAAA,EAAQ,QAAA,EACR,QAAA,UACA,OAAA,GAAU,UAAA,GACT,OAAA,CAAQ,eAAA;EA5GW;;;EAwIT,GAAA,CAAI,QAAA,WAAmB,OAAA,CAAQ,MAAA;EApHlC;;;EAiIG,SAAA,CAAU,QAAA,WAAmB,OAAA,CAAQ,QAAA;;;;EAarC,MAAA,CAAO,QAAA,WAAmB,OAAA;EAnHpB;;;EAiIN,UAAA,CAAW,SAAA,aAAsB,OAAA,CAAQ,gBAAA;EArGpD;;;EA2HW,eAAA,CAAgB,aAAA,WAAqB,OAAA;EAxH/C;;;EAiIU,MAAA,CAAO,QAAA,WAAmB,OAAA;EAtGrC;;;EAkHK,GAAA,CAAI,QAAA;EA/GR;;;;;;;EA0HU,YAAA,CAAa,QAAA,UAAkB,SAAA,YAAmB,OAAA;EAjFrB;;;;;;EAmGnC,oBAAA,CAAqB,QAAA,UAAkB,SAAA;EAxEA;;;;;;EAgGjC,sBAAA,CAAuB,KAAA,WAAgB,OAAA,CAAQ,wBAAA;EAjErB;;;EA6I1B,QAAA,CAAS,QAAA,WAAmB,OAAA,CAAQ,eAAA;EAtHvB;;;EAmJb,IAAA,CAAK,QAAA,WAAmB,OAAA;EAjIT;;;EA6If,IAAA,CAAK,IAAA,UAAc,EAAA,WAAa,OAAA,CAAQ,eAAA;EArHD;;;EAiJvC,IAAA,CAAK,IAAA,UAAc,EAAA,WAAa,OAAA,CAAQ,eAAA;EArEZ;;;EAiG5B,IAAA,CAAK,SAAA,UAAmB,OAAA,GAAU,WAAA,GAAc,OAAA,CAAQ,eAAA;EApEhC;;;EAoH9B,IAAA,CAAK,QAAA;EAxGiC;;;EA+GtC,OAAA,CAAA;EAnFyB;;;EAAA,UA8FtB,eAAA,CAAgB,QAAA;EAlER;;;EAAA,UA0EF,QAAA,CAAS,IAAA,EAAM,MAAA,YAAkB,YAAA,GAAe,OAAA,CAAQ,MAAA;EA1EH;;;EAAA,UAyF3D,aAAA,CAAc,MAAA,EAAQ,MAAA;EAvBtB;;;EAAA,UA8BA,aAAA,CAAc,QAAA;AAAA"}

package/esm/storage/drivers/local-driver.mjs

@@ -0,0 +1,379 @@
+import { storagePath } from "../../utils/paths.mjs";
+import { url } from "../../utils/urls.mjs";
+import { storageDriverContext } from "../context/storage-driver-context.mjs";
+import { getMimeType } from "../utils/mime.mjs";
+import { dirname, join } from "path";
+import { ltrim } from "@mongez/reinforcements";
+import { directoryExistsAsync, ensureDirectoryAsync, fileExistsAsync, removeDirectoryAsync, unlinkAsync } from "@warlock.js/fs";
+import { createReadStream, createWriteStream } from "fs";
+import { copyFile, readFile, readdir, rename, stat, writeFile } from "fs/promises";
+import crypto from "crypto";
+import { pipeline } from "stream/promises";
+
+//#region ../../@warlock.js/core/src/storage/drivers/local-driver.ts
+/**
+* Local filesystem storage driver
+*
+* Stores files on the local filesystem with support for:
+* - File operations (put, get, delete, copy, move)
+* - Stream operations for large files
+* - Batch operations
+* - Signed temporary URLs
+*/
+var LocalDriver = class {
+	constructor(options = {}) {
+		this.options = options;
+		this.name = "local";
+		this.urlPrefix = "";
+		this._metadata = /* @__PURE__ */ new Map();
+		this.root = options.root ?? storagePath();
+		this.urlPrefix = options.urlPrefix ?? "";
+		this.temporaryUrlPrefix = options.temporaryUrlPrefix ?? "/temp-files";
+		this.signatureKey = options.signatureKey;
+	}
+	/**
+	* Apply prefix to location path
+	*
+	* Priority: context prefix > driver options prefix > no prefix
+	* This allows multi-tenant scenarios where context overrides driver config.
+	*
+	* @param location - Original location path
+	* @returns Location with prefix applied if one exists
+	*/
+	applyPrefix(location) {
+		const prefix = storageDriverContext.getPrefix() || this.options.prefix;
+		if (!prefix) return location;
+		const cleanPrefix = prefix.replace(/\/+$/, "");
+		const cleanLocation = location.replace(/^\/+/, "");
+		if (cleanLocation.startsWith(cleanPrefix + "/") || cleanLocation === cleanPrefix) return cleanLocation;
+		return `${cleanPrefix}/${cleanLocation}`;
+	}
+	/**
+	* Put file to local storage
+	*/
+	async put(file, location, options) {
+		const absolutePath = this.getAbsolutePath(location);
+		await ensureDirectoryAsync(dirname(absolutePath));
+		const fileBuffer = await this.toBuffer(file);
+		const hash = this.calculateHash(fileBuffer);
+		await writeFile(absolutePath, new Uint8Array(fileBuffer));
+		const stats = await stat(absolutePath);
+		const mimeType = options?.mimeType || this.guessMimeType(location);
+		return {
+			path: location,
+			url: this.url(location),
+			size: stats.size,
+			hash,
+			mimeType,
+			driver: this.name
+		};
+	}
+	/**
+	* Put file from a readable stream (for large files)
+	*/
+	async putStream(stream, location, options) {
+		const absolutePath = this.getAbsolutePath(location);
+		await ensureDirectoryAsync(dirname(absolutePath));
+		await pipeline(stream, createWriteStream(absolutePath));
+		const fileBuffer = await readFile(absolutePath);
+		const hash = this.calculateHash(fileBuffer);
+		const stats = await stat(absolutePath);
+		const mimeType = options?.mimeType || this.guessMimeType(location);
+		return {
+			path: location,
+			url: this.url(location),
+			size: stats.size,
+			hash,
+			mimeType,
+			driver: this.name
+		};
+	}
+	/**
+	* Get file contents as Buffer
+	*/
+	async get(location) {
+		const absolutePath = this.getAbsolutePath(location);
+		if (!await fileExistsAsync(absolutePath)) throw new Error(`File not found: ${location}`);
+		return readFile(absolutePath);
+	}
+	/**
+	* Get file as a readable stream (for large files)
+	*/
+	async getStream(location) {
+		const absolutePath = this.getAbsolutePath(location);
+		if (!await fileExistsAsync(absolutePath)) throw new Error(`File not found: ${location}`);
+		return createReadStream(absolutePath);
+	}
+	/**
+	* Delete a file
+	*/
+	async delete(location) {
+		const absolutePath = this.getAbsolutePath(location);
+		if (!await fileExistsAsync(absolutePath)) return false;
+		await unlinkAsync(absolutePath);
+		return true;
+	}
+	/**
+	* Delete multiple files at once
+	*/
+	async deleteMany(locations) {
+		const results = [];
+		for (const location of locations) try {
+			const deleted = await this.delete(location);
+			results.push({
+				location,
+				deleted
+			});
+		} catch (error) {
+			results.push({
+				location,
+				deleted: false,
+				error: error instanceof Error ? error.message : "Unknown error"
+			});
+		}
+		return results;
+	}
+	/**
+	* Delete directory
+	*/
+	async deleteDirectory(directoryPath) {
+		await removeDirectoryAsync(directoryPath);
+		return true;
+	}
+	/**
+	* Check if file exists
+	*/
+	async exists(location) {
+		const absolutePath = this.getAbsolutePath(location);
+		return Boolean(await fileExistsAsync(absolutePath));
+	}
+	/**
+	* Get public URL for file
+	*/
+	url(location) {
+		return url(this.urlPrefix + "/" + ltrim(location, "/"));
+	}
+	/**
+	* Get a temporary signed URL that expires
+	* Returns a clean URL with encoded token: {temporaryUrlPrefix}/{token}
+	*
+	* @param location - File path
+	* @param expiresIn - Seconds until expiration (default: 3600)
+	*/
+	async temporaryUrl(location, expiresIn = 3600) {
+		if (!this.signatureKey) throw new Error("Temporary URLs require a signatureKey in LocalDriver options. Configure storage.drivers.local.signatureKey in your config.");
+		const token = this.encodeTemporaryToken(location, expiresIn);
+		return `${this.temporaryUrlPrefix}/${token}`;
+	}
+	/**
+	* Encode a temporary token containing path, expiry, and signature
+	*
+	* @param location - File path
+	* @param expiresIn - Seconds until expiration
+	*/
+	encodeTemporaryToken(location, expiresIn) {
+		if (!this.signatureKey) throw new Error("Temporary tokens require a signatureKey");
+		const exp = Math.floor(Date.now() / 1e3) + expiresIn;
+		const payload = {
+			path: location,
+			exp,
+			sig: crypto.createHmac("sha256", this.signatureKey).update(`${location}:${exp}`).digest("hex")
+		};
+		const json = JSON.stringify(payload);
+		return Buffer.from(json).toString("base64url");
+	}
+	/**
+	* Validate a temporary URL token
+	* Returns a result object with validation status, file info, and convenience methods
+	*
+	* @param token - The token from the URL
+	*/
+	async validateTemporaryToken(token) {
+		if (!this.signatureKey) return {
+			valid: false,
+			error: "missing_key"
+		};
+		let payload;
+		try {
+			const json = Buffer.from(token, "base64url").toString("utf-8");
+			payload = JSON.parse(json);
+		} catch {
+			return {
+				valid: false,
+				error: "invalid_token"
+			};
+		}
+		if (!payload.path || !payload.exp || !payload.sig) return {
+			valid: false,
+			error: "invalid_token"
+		};
+		const now = Math.floor(Date.now() / 1e3);
+		if (payload.exp < now) return {
+			valid: false,
+			error: "expired"
+		};
+		const expectedSig = crypto.createHmac("sha256", this.signatureKey).update(`${payload.path}:${payload.exp}`).digest("hex");
+		const sigBuffer = Buffer.from(payload.sig, "hex");
+		const expectedBuffer = Buffer.from(expectedSig, "hex");
+		if (sigBuffer.length !== expectedBuffer.length) return {
+			valid: false,
+			error: "invalid_signature"
+		};
+		if (!crypto.timingSafeEqual(new Uint8Array(sigBuffer), new Uint8Array(expectedBuffer))) return {
+			valid: false,
+			error: "invalid_signature"
+		};
+		const absolutePath = this.getAbsolutePath(payload.path);
+		if (!await fileExistsAsync(absolutePath)) return {
+			valid: false,
+			error: "file_not_found"
+		};
+		return {
+			valid: true,
+			path: payload.path,
+			absolutePath,
+			expiresAt: /* @__PURE__ */ new Date(payload.exp * 1e3),
+			mimeType: this.guessMimeType(payload.path),
+			driver: this,
+			getFile: () => this.get(payload.path),
+			getStream: () => this.getStream(payload.path)
+		};
+	}
+	/**
+	* Get file info/metadata without downloading
+	*/
+	async metadata(location) {
+		if (this._metadata.has(location)) return this._metadata.get(location);
+		const absolutePath = this.getAbsolutePath(location);
+		if (!await fileExistsAsync(absolutePath)) throw new Error(`File not found: ${absolutePath}`);
+		const stats = await stat(absolutePath);
+		const name = location.split("/").pop() || "";
+		this._metadata.set(location, {
+			path: location,
+			name,
+			size: stats.size,
+			isDirectory: stats.isDirectory(),
+			lastModified: stats.mtime,
+			mimeType: this.guessMimeType(location)
+		});
+		return this._metadata.get(location);
+	}
+	/**
+	* Get file size in bytes (shortcut for metadata().size)
+	*/
+	async size(location) {
+		return (await this.metadata(location)).size;
+	}
+	/**
+	* Copy file to a new location
+	*/
+	async copy(from, to) {
+		const fromPath = this.getAbsolutePath(from);
+		const toPath = this.getAbsolutePath(to);
+		if (!await fileExistsAsync(fromPath)) throw new Error(`Source file not found: ${from}`);
+		await ensureDirectoryAsync(dirname(toPath));
+		await copyFile(fromPath, toPath);
+		const fileBuffer = await readFile(toPath);
+		const hash = this.calculateHash(fileBuffer);
+		const stats = await stat(toPath);
+		return {
+			path: to,
+			url: this.url(to),
+			size: stats.size,
+			hash,
+			mimeType: this.guessMimeType(to),
+			driver: this.name
+		};
+	}
+	/**
+	* Move file to a new location
+	*/
+	async move(from, to) {
+		const fromPath = this.getAbsolutePath(from);
+		const toPath = this.getAbsolutePath(to);
+		if (!await fileExistsAsync(fromPath)) throw new Error(`Source file not found: ${from}`);
+		await ensureDirectoryAsync(dirname(toPath));
+		await rename(fromPath, toPath);
+		const fileBuffer = await readFile(toPath);
+		const hash = this.calculateHash(fileBuffer);
+		const stats = await stat(toPath);
+		return {
+			path: to,
+			url: this.url(to),
+			size: stats.size,
+			hash,
+			mimeType: this.guessMimeType(to),
+			driver: this.name
+		};
+	}
+	/**
+	* List files in a directory
+	*/
+	async list(directory, options) {
+		const absolutePath = this.getAbsolutePath(directory);
+		const files = [];
+		if (!await directoryExistsAsync(absolutePath)) return files;
+		const entries = await readdir(absolutePath, { withFileTypes: true });
+		for (const entry of entries) {
+			const entryPath = join(directory, entry.name);
+			const entryStats = await stat(this.getAbsolutePath(entryPath));
+			files.push({
+				path: entryPath,
+				name: entry.name,
+				size: entryStats.size,
+				isDirectory: entry.isDirectory(),
+				lastModified: entryStats.mtime,
+				mimeType: entry.isFile() ? this.guessMimeType(entry.name) : void 0
+			});
+			if (options?.recursive && entry.isDirectory()) {
+				const subFiles = await this.list(entryPath, options);
+				files.push(...subFiles);
+			}
+			if (options?.limit && files.length >= options.limit) break;
+		}
+		return files;
+	}
+	/**
+	* Get absolute filesystem path for a location
+	*/
+	path(location) {
+		return this.getAbsolutePath(location);
+	}
+	/**
+	* Get the storage root directory
+	*/
+	getRoot() {
+		return this.root;
+	}
+	/**
+	* Get absolute file path
+	*/
+	getAbsolutePath(location) {
+		const prefixedLocation = this.applyPrefix(location);
+		return join(this.root, prefixedLocation);
+	}
+	/**
+	* Convert various input types to Buffer
+	*/
+	async toBuffer(file) {
+		if (Buffer.isBuffer(file)) return file;
+		if (typeof file === "string") return readFile(file);
+		return file.buffer();
+	}
+	/**
+	* Calculate SHA-256 hash
+	*/
+	calculateHash(buffer) {
+		return crypto.createHash("sha256").update(new Uint8Array(buffer)).digest("hex");
+	}
+	/**
+	* Guess MIME type from file extension
+	*/
+	guessMimeType(location) {
+		return getMimeType(location);
+	}
+};
+
+//#endregion
+export { LocalDriver };
+//# sourceMappingURL=local-driver.mjs.map