@rezwanul7/storage 0.0.0 → 0.1.0

package/dist/server/index.d.cts

@@ -0,0 +1,269 @@
+import { S as SharedFileRules } from '../fileRules.types-CGXBnwzd.cjs';
+
+/** The full Rules the server checks: the shared size and extension Rules, MIME and block lists, and your own checks. */
+interface ServerValidationRules extends SharedFileRules {
+    /** MIME types a file's bytes may show. Any is allowed when omitted. */
+    allowedMimeTypes?: string[];
+    /** MIME types to reject. */
+    blockedMimeTypes?: string[];
+    /** Extensions to reject, lower case and without the dot. */
+    blockedExtensions?: string[];
+    /** Your own checks, run after the built-in ones. */
+    customValidators?: ServerFileValidator[];
+}
+/**
+ * Your own check on an uploaded file. Return a message to reject the file, or nothing to accept it.
+ *
+ * @param params - The file's bytes and what is known about its type.
+ * @returns A message that is safe to show to users, or nothing.
+ */
+type ServerFileValidator = (params: ServerFileValidationContext) => Promise<string | null | undefined> | string | null | undefined;
+/** What a {@link ServerFileValidator} receives about the file it checks. */
+interface ServerFileValidationContext {
+    /** The file's bytes. */
+    buffer: Uint8Array;
+    /** The name the file was uploaded with. */
+    originalName: string;
+    /** The MIME type the browser declared, if any. */
+    declaredMime: string | undefined;
+    /** The MIME type its bytes show, or the best guess from its name. */
+    detectedMime: string | undefined;
+    /** The extension its bytes show, or the one in its name. */
+    detectedExt: string | undefined;
+    /** The file's size, in bytes. */
+    size: number;
+}
+
+/**
+ * Where the package logs failures it handles itself. A `@rezwanul7/logger` instance fits it as is.
+ */
+interface StorageLogger {
+    /**
+     * Logs a failure the package recovered from, such as `storage.rollback_delete_failed`.
+     *
+     * @param event - The event name.
+     * @param data - Structured context.
+     */
+    error(event: string, data?: Record<string, unknown>): void;
+}
+/** One file an Upload stored. */
+interface FileUploadResult {
+    /** The name the file was uploaded with. */
+    originalFileName: string;
+    /** The name of the Provider that stored the file. Save it: read and delete the file through the same Provider. */
+    provider: string;
+    /** The file's Storage ID. Save it to read or delete the file later. */
+    storageId: string;
+    /** The Provider's URL for the file. `LocalFileStorage`'s isn't served; serve files through the app. */
+    url: string;
+    /** The file's size, in bytes. */
+    size: number;
+    /** The MIME type its bytes show, not the one the browser declared. */
+    mime: string;
+    /** The extension its bytes show, lower case and without the dot. */
+    ext: string;
+}
+/**
+ * What {@link FileUpload.store} did: stored every file, or stored none and says why. Errors are keyed by the file's
+ * index, and their messages are safe to show to users.
+ */
+type FileStoreResult = {
+    /** Every file was stored. */
+    ok: true;
+    /** The stored files, in the order given. */
+    files: FileUploadResult[];
+} | {
+    /** No file was stored. */
+    ok: false;
+    /** Each failed file's messages, keyed by its index. */
+    errors: Record<number, string[]>;
+};
+/** Checks untrusted files and stores them; built by `createFileUpload`. */
+interface FileUpload {
+    /**
+     * Checks every file against `rules` and stores them under `directory` only when all of them pass. If storing one
+     * fails, the files stored before it are deleted and a `StorageError` is thrown, so nothing is left half-stored.
+     *
+     * @param files - One file or several.
+     * @param rules - The Rules every file must satisfy.
+     * @param options - The folder to store the files under.
+     * @returns The stored files, or every failed file's messages keyed by its index in `files` (0 for a single file).
+     */
+    store(files: File | File[], rules: ServerValidationRules, options: {
+        directory: string;
+    }): Promise<FileStoreResult>;
+}
+
+/** What a Storage returns for a file it stored. */
+interface StorageUploadResult {
+    /** The Provider's URL for the file. It is not necessarily served to browsers. */
+    url: string;
+    /** The Storage ID: the key the Storage gave the file, such as a path or an object key. */
+    storageId: string;
+    /** The stored size, in bytes. */
+    size: number;
+    /** The MIME type the file was stored with. */
+    mime: string;
+}
+/** A stored file read back from its Provider. */
+interface StoredFile {
+    /** The file's bytes. */
+    stream: ReadableStream<Uint8Array>;
+    /** The file's size, in bytes. */
+    size: number;
+}
+/**
+ * The adapter to one kind of Provider. Implement it to add a Provider: pick each file's key under the given
+ * `directory`, take settings as constructor options, and throw `StorageError` with `STORAGE_INVALID_ID` for a
+ * Storage ID outside the Provider.
+ */
+interface FileStorage {
+    /** The Provider's name, saved with each file, such as `"local"`. Read and delete a file through the same one. */
+    readonly provider: string;
+    /**
+     * Stores one checked file.
+     *
+     * @param params - The file's bytes, its MIME type and extension, and the folder to store it under. The Storage
+     * picks the file's own name.
+     * @returns Where the file was stored.
+     */
+    upload(params: {
+        buffer: Uint8Array;
+        mime: string;
+        ext: string;
+        directory: string;
+    }): Promise<StorageUploadResult>;
+    /**
+     * Reads a stored file.
+     *
+     * @param storageId - The file's Storage ID.
+     * @returns The file, or null when nothing is stored under `storageId`.
+     */
+    read(storageId: string): Promise<StoredFile | null>;
+    /**
+     * Deletes a stored file. Deleting a file that isn't there succeeds.
+     *
+     * @param storageId - The file's Storage ID.
+     */
+    delete(storageId: string): Promise<void>;
+    /**
+     * The Provider's URL for a stored file.
+     *
+     * @param storageId - The file's Storage ID.
+     * @returns The URL. It is not necessarily served to browsers.
+     */
+    getUrl(storageId: string): string;
+    /**
+     * Whether a file is stored under `storageId`. Optional.
+     *
+     * @param storageId - The file's Storage ID.
+     * @returns True when a file is stored there.
+     */
+    exists?(storageId: string): Promise<boolean>;
+}
+
+/** What {@link createFileUpload} needs. */
+interface FileUploadOptions {
+    /** The Storage checked files are stored through. */
+    storage: FileStorage;
+    /**
+     * Where files a failed Upload couldn't remove are logged, as `storage.rollback_delete_failed`. Defaults to a logger
+     * that writes nothing.
+     */
+    logger?: StorageLogger;
+}
+/**
+ * Builds the uploader, which checks untrusted files and stores them through `storage`.
+ *
+ * @param options - The Storage and an optional logger.
+ * @returns The uploader.
+ *
+ * @example
+ * const uploader = createFileUpload({ storage: new LocalFileStorage({ root: "./uploads", urlPrefix: "/uploads" }) });
+ */
+declare function createFileUpload({ storage, logger, }: FileUploadOptions): FileUpload;
+
+/** Settings of a {@link LocalFileStorage}. */
+interface LocalFileStorageOptions {
+    /** Folder the files are stored under. Keep it outside `public/`. */
+    root: string;
+    /** Prefix of the URL `getUrl` returns, without a trailing slash, e.g. "/uploads". */
+    urlPrefix: string;
+}
+/**
+ * The Storage for the server's disk, Provider name `"local"`. Keep `root` outside any folder the web server serves, so
+ * nothing is served without going through the app.
+ *
+ * @example
+ * const storage = new LocalFileStorage({ root: "./uploads", urlPrefix: "/uploads" });
+ */
+declare class LocalFileStorage implements FileStorage {
+    /** The Provider's name, saved with each file. */
+    readonly provider = "local";
+    private readonly root;
+    private readonly urlPrefix;
+    /**
+     * @param options - The folder to store under and the URL prefix.
+     */
+    constructor({ root, urlPrefix }: LocalFileStorageOptions);
+    /**
+     * Writes a file under `directory` with a random name.
+     *
+     * @param params - The file's bytes, MIME type, extension and folder.
+     * @returns Where the file was stored.
+     */
+    upload({ buffer, mime, ext, directory, }: Parameters<FileStorage["upload"]>[0]): Promise<StorageUploadResult>;
+    /**
+     * Reads a stored file as a stream.
+     *
+     * @param storageId - The file's Storage ID.
+     * @returns The file, or null when nothing is stored there.
+     */
+    read(storageId: string): Promise<StoredFile | null>;
+    /**
+     * Deletes a stored file; succeeds when it isn't there.
+     *
+     * @param storageId - The file's Storage ID.
+     */
+    delete(storageId: string): Promise<void>;
+    /**
+     * The file's URL under `urlPrefix`. Nothing serves it until your app does.
+     *
+     * @param storageId - The file's Storage ID.
+     * @returns The URL.
+     */
+    getUrl(storageId: string): string;
+    /** Maps a storage ID to a path under the root, refusing IDs that would escape it. */
+    private resolve;
+}
+
+/**
+ * The stable code of a {@link StorageError}.
+ *
+ * - `STORAGE_INVALID_ID`: the Storage ID points outside the Provider (a bug or a tampered ID).
+ * - `STORAGE_UPLOAD_FAILED`: the Storage couldn't store a file; `cause` is its error.
+ */
+type StorageErrorCode = "STORAGE_INVALID_ID" | "STORAGE_UPLOAD_FAILED";
+/**
+ * A storage operation failed. Branch on `code`; `cause` is the Provider's error and `meta` its context, for logs. The
+ * message is for developers: the caller decides what its users see.
+ */
+declare class StorageError extends Error {
+    /** Always `"StorageError"`. */
+    readonly name = "StorageError";
+    /** Stable code naming what went wrong. */
+    readonly code: StorageErrorCode;
+    /** Context for logs, such as the Provider's name. */
+    readonly meta?: Record<string, unknown>;
+    /**
+     * @param code - The stable code.
+     * @param opts - The message, the underlying `cause` and context for logs.
+     */
+    constructor(code: StorageErrorCode, opts: {
+        message: string;
+        cause?: unknown;
+        meta?: Record<string, unknown>;
+    });
+}
+
+export { type FileStorage, type FileStoreResult, type FileUpload, type FileUploadOptions, type FileUploadResult, LocalFileStorage, type LocalFileStorageOptions, type ServerFileValidationContext, type ServerFileValidator, type ServerValidationRules, StorageError, type StorageErrorCode, type StorageLogger, type StorageUploadResult, type StoredFile, createFileUpload };

package/dist/server/index.d.ts

@@ -0,0 +1,269 @@
+import { S as SharedFileRules } from '../fileRules.types-CGXBnwzd.js';
+
+/** The full Rules the server checks: the shared size and extension Rules, MIME and block lists, and your own checks. */
+interface ServerValidationRules extends SharedFileRules {
+    /** MIME types a file's bytes may show. Any is allowed when omitted. */
+    allowedMimeTypes?: string[];
+    /** MIME types to reject. */
+    blockedMimeTypes?: string[];
+    /** Extensions to reject, lower case and without the dot. */
+    blockedExtensions?: string[];
+    /** Your own checks, run after the built-in ones. */
+    customValidators?: ServerFileValidator[];
+}
+/**
+ * Your own check on an uploaded file. Return a message to reject the file, or nothing to accept it.
+ *
+ * @param params - The file's bytes and what is known about its type.
+ * @returns A message that is safe to show to users, or nothing.
+ */
+type ServerFileValidator = (params: ServerFileValidationContext) => Promise<string | null | undefined> | string | null | undefined;
+/** What a {@link ServerFileValidator} receives about the file it checks. */
+interface ServerFileValidationContext {
+    /** The file's bytes. */
+    buffer: Uint8Array;
+    /** The name the file was uploaded with. */
+    originalName: string;
+    /** The MIME type the browser declared, if any. */
+    declaredMime: string | undefined;
+    /** The MIME type its bytes show, or the best guess from its name. */
+    detectedMime: string | undefined;
+    /** The extension its bytes show, or the one in its name. */
+    detectedExt: string | undefined;
+    /** The file's size, in bytes. */
+    size: number;
+}
+
+/**
+ * Where the package logs failures it handles itself. A `@rezwanul7/logger` instance fits it as is.
+ */
+interface StorageLogger {
+    /**
+     * Logs a failure the package recovered from, such as `storage.rollback_delete_failed`.
+     *
+     * @param event - The event name.
+     * @param data - Structured context.
+     */
+    error(event: string, data?: Record<string, unknown>): void;
+}
+/** One file an Upload stored. */
+interface FileUploadResult {
+    /** The name the file was uploaded with. */
+    originalFileName: string;
+    /** The name of the Provider that stored the file. Save it: read and delete the file through the same Provider. */
+    provider: string;
+    /** The file's Storage ID. Save it to read or delete the file later. */
+    storageId: string;
+    /** The Provider's URL for the file. `LocalFileStorage`'s isn't served; serve files through the app. */
+    url: string;
+    /** The file's size, in bytes. */
+    size: number;
+    /** The MIME type its bytes show, not the one the browser declared. */
+    mime: string;
+    /** The extension its bytes show, lower case and without the dot. */
+    ext: string;
+}
+/**
+ * What {@link FileUpload.store} did: stored every file, or stored none and says why. Errors are keyed by the file's
+ * index, and their messages are safe to show to users.
+ */
+type FileStoreResult = {
+    /** Every file was stored. */
+    ok: true;
+    /** The stored files, in the order given. */
+    files: FileUploadResult[];
+} | {
+    /** No file was stored. */
+    ok: false;
+    /** Each failed file's messages, keyed by its index. */
+    errors: Record<number, string[]>;
+};
+/** Checks untrusted files and stores them; built by `createFileUpload`. */
+interface FileUpload {
+    /**
+     * Checks every file against `rules` and stores them under `directory` only when all of them pass. If storing one
+     * fails, the files stored before it are deleted and a `StorageError` is thrown, so nothing is left half-stored.
+     *
+     * @param files - One file or several.
+     * @param rules - The Rules every file must satisfy.
+     * @param options - The folder to store the files under.
+     * @returns The stored files, or every failed file's messages keyed by its index in `files` (0 for a single file).
+     */
+    store(files: File | File[], rules: ServerValidationRules, options: {
+        directory: string;
+    }): Promise<FileStoreResult>;
+}
+
+/** What a Storage returns for a file it stored. */
+interface StorageUploadResult {
+    /** The Provider's URL for the file. It is not necessarily served to browsers. */
+    url: string;
+    /** The Storage ID: the key the Storage gave the file, such as a path or an object key. */
+    storageId: string;
+    /** The stored size, in bytes. */
+    size: number;
+    /** The MIME type the file was stored with. */
+    mime: string;
+}
+/** A stored file read back from its Provider. */
+interface StoredFile {
+    /** The file's bytes. */
+    stream: ReadableStream<Uint8Array>;
+    /** The file's size, in bytes. */
+    size: number;
+}
+/**
+ * The adapter to one kind of Provider. Implement it to add a Provider: pick each file's key under the given
+ * `directory`, take settings as constructor options, and throw `StorageError` with `STORAGE_INVALID_ID` for a
+ * Storage ID outside the Provider.
+ */
+interface FileStorage {
+    /** The Provider's name, saved with each file, such as `"local"`. Read and delete a file through the same one. */
+    readonly provider: string;
+    /**
+     * Stores one checked file.
+     *
+     * @param params - The file's bytes, its MIME type and extension, and the folder to store it under. The Storage
+     * picks the file's own name.
+     * @returns Where the file was stored.
+     */
+    upload(params: {
+        buffer: Uint8Array;
+        mime: string;
+        ext: string;
+        directory: string;
+    }): Promise<StorageUploadResult>;
+    /**
+     * Reads a stored file.
+     *
+     * @param storageId - The file's Storage ID.
+     * @returns The file, or null when nothing is stored under `storageId`.
+     */
+    read(storageId: string): Promise<StoredFile | null>;
+    /**
+     * Deletes a stored file. Deleting a file that isn't there succeeds.
+     *
+     * @param storageId - The file's Storage ID.
+     */
+    delete(storageId: string): Promise<void>;
+    /**
+     * The Provider's URL for a stored file.
+     *
+     * @param storageId - The file's Storage ID.
+     * @returns The URL. It is not necessarily served to browsers.
+     */
+    getUrl(storageId: string): string;
+    /**
+     * Whether a file is stored under `storageId`. Optional.
+     *
+     * @param storageId - The file's Storage ID.
+     * @returns True when a file is stored there.
+     */
+    exists?(storageId: string): Promise<boolean>;
+}
+
+/** What {@link createFileUpload} needs. */
+interface FileUploadOptions {
+    /** The Storage checked files are stored through. */
+    storage: FileStorage;
+    /**
+     * Where files a failed Upload couldn't remove are logged, as `storage.rollback_delete_failed`. Defaults to a logger
+     * that writes nothing.
+     */
+    logger?: StorageLogger;
+}
+/**
+ * Builds the uploader, which checks untrusted files and stores them through `storage`.
+ *
+ * @param options - The Storage and an optional logger.
+ * @returns The uploader.
+ *
+ * @example
+ * const uploader = createFileUpload({ storage: new LocalFileStorage({ root: "./uploads", urlPrefix: "/uploads" }) });
+ */
+declare function createFileUpload({ storage, logger, }: FileUploadOptions): FileUpload;
+
+/** Settings of a {@link LocalFileStorage}. */
+interface LocalFileStorageOptions {
+    /** Folder the files are stored under. Keep it outside `public/`. */
+    root: string;
+    /** Prefix of the URL `getUrl` returns, without a trailing slash, e.g. "/uploads". */
+    urlPrefix: string;
+}
+/**
+ * The Storage for the server's disk, Provider name `"local"`. Keep `root` outside any folder the web server serves, so
+ * nothing is served without going through the app.
+ *
+ * @example
+ * const storage = new LocalFileStorage({ root: "./uploads", urlPrefix: "/uploads" });
+ */
+declare class LocalFileStorage implements FileStorage {
+    /** The Provider's name, saved with each file. */
+    readonly provider = "local";
+    private readonly root;
+    private readonly urlPrefix;
+    /**
+     * @param options - The folder to store under and the URL prefix.
+     */
+    constructor({ root, urlPrefix }: LocalFileStorageOptions);
+    /**
+     * Writes a file under `directory` with a random name.
+     *
+     * @param params - The file's bytes, MIME type, extension and folder.
+     * @returns Where the file was stored.
+     */
+    upload({ buffer, mime, ext, directory, }: Parameters<FileStorage["upload"]>[0]): Promise<StorageUploadResult>;
+    /**
+     * Reads a stored file as a stream.
+     *
+     * @param storageId - The file's Storage ID.
+     * @returns The file, or null when nothing is stored there.
+     */
+    read(storageId: string): Promise<StoredFile | null>;
+    /**
+     * Deletes a stored file; succeeds when it isn't there.
+     *
+     * @param storageId - The file's Storage ID.
+     */
+    delete(storageId: string): Promise<void>;
+    /**
+     * The file's URL under `urlPrefix`. Nothing serves it until your app does.
+     *
+     * @param storageId - The file's Storage ID.
+     * @returns The URL.
+     */
+    getUrl(storageId: string): string;
+    /** Maps a storage ID to a path under the root, refusing IDs that would escape it. */
+    private resolve;
+}
+
+/**
+ * The stable code of a {@link StorageError}.
+ *
+ * - `STORAGE_INVALID_ID`: the Storage ID points outside the Provider (a bug or a tampered ID).
+ * - `STORAGE_UPLOAD_FAILED`: the Storage couldn't store a file; `cause` is its error.
+ */
+type StorageErrorCode = "STORAGE_INVALID_ID" | "STORAGE_UPLOAD_FAILED";
+/**
+ * A storage operation failed. Branch on `code`; `cause` is the Provider's error and `meta` its context, for logs. The
+ * message is for developers: the caller decides what its users see.
+ */
+declare class StorageError extends Error {
+    /** Always `"StorageError"`. */
+    readonly name = "StorageError";
+    /** Stable code naming what went wrong. */
+    readonly code: StorageErrorCode;
+    /** Context for logs, such as the Provider's name. */
+    readonly meta?: Record<string, unknown>;
+    /**
+     * @param code - The stable code.
+     * @param opts - The message, the underlying `cause` and context for logs.
+     */
+    constructor(code: StorageErrorCode, opts: {
+        message: string;
+        cause?: unknown;
+        meta?: Record<string, unknown>;
+    });
+}
+
+export { type FileStorage, type FileStoreResult, type FileUpload, type FileUploadOptions, type FileUploadResult, LocalFileStorage, type LocalFileStorageOptions, type ServerFileValidationContext, type ServerFileValidator, type ServerValidationRules, StorageError, type StorageErrorCode, type StorageLogger, type StorageUploadResult, type StoredFile, createFileUpload };