@rezwanul7/storage 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rezwanul Islam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,208 @@
-# Temporary Holding Version
+# @rezwanul7/storage
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Check files that users upload and keep them with a Provider of your choice. The server reads each file's bytes to
+find its real type, rejects dangerous and disguised files, checks your Rules, and stores the Upload through a Storage.
+The same Rules give the browser early feedback before anything is sent. The terms are defined in the
+[glossary](./GLOSSARY.md).
+
+## Installation
+
+```bash
+npm install @rezwanul7/storage
+# or
+pnpm add @rezwanul7/storage
+```
+
+`zod` is an optional peer dependency, used only by the form schemas. Install it if you import
+`@rezwanul7/storage/zod`:
+
+```bash
+pnpm add zod
+```
+
+The supported range is `^4.0.0`.
+
+## Entry points
+
+| Import                      | Contents                                                                                       | Runs in          |
+| --------------------------- | ---------------------------------------------------------------------------------------------- | ---------------- |
+| `@rezwanul7/storage`        | `SharedFileRules`, file sizes, `detectFileTypeFromName`, `getFileExtension`, File categories   | Browser and Node |
+| `@rezwanul7/storage/zod`    | `createSingleFileZodSchema`, `createMultiFileZodSchema` (needs `zod` installed)                | Browser and Node |
+| `@rezwanul7/storage/server` | `createFileUpload`, `ServerValidationRules`, `FileStorage`, `LocalFileStorage`, `StorageError` | Node             |
+
+## Quick start
+
+```ts
+// uploadRules.ts: one set of Rules for the browser and the server
+import type { ServerValidationRules } from "@rezwanul7/storage/server";
+
+export const avatarRules: ServerValidationRules = {
+  maxFileSize: "2MB",
+  allowedExtensions: ["png", "jpg", "jpeg"],
+  allowedMimeTypes: ["image/png", "image/jpeg"],
+};
+```
+
+```ts
+// In a form: checks size and extension before uploading
+import { z } from "zod";
+import { createSingleFileZodSchema } from "@rezwanul7/storage/zod";
+
+const schema = z.object({ avatar: createSingleFileZodSchema(avatarRules) });
+```
+
+```ts
+// On the server: checks the bytes, then stores
+import { createFileUpload, LocalFileStorage } from "@rezwanul7/storage/server";
+
+const storage = new LocalFileStorage({
+  root: "./uploads",
+  urlPrefix: "/uploads",
+});
+const uploader = createFileUpload({ storage, logger });
+
+const result = await uploader.store(file, avatarRules, {
+  directory: "avatars",
+});
+if (!result.ok) return { fieldErrors: { avatar: result.errors[0] } };
+
+const [uploaded] = result.files;
+// Save uploaded.provider and uploaded.storageId: you need both to read or delete the file later.
+```
+
+`logger` is optional. Pass a `@rezwanul7/logger` instance, or anything with `error(event, data)`, to hear about a file
+a failed Upload couldn't clean up (`storage.rollback_delete_failed`). Without one, nothing is logged.
+
+## Wiring it into your app
+
+Build the Storage once, in your own code, from your own configuration:
+
+```ts
+export function createStorage(provider = config.storageProvider): FileStorage {
+  switch (provider) {
+    case "local":
+      return new LocalFileStorage({
+        root: config.uploadRoot,
+        urlPrefix: "/uploads",
+      });
+    default:
+      throw new Error(`Unknown storage provider: ${provider}`);
+  }
+}
+```
+
+- Save `provider` with each stored file. To read or delete it, build the Storage for that Provider, not the current
+  default, so files stay reachable after you switch Providers.
+- `LocalFileStorage` keeps files under `root`, and its `url` isn't served. Keep `root` outside any folder your web
+  server serves, and serve files from a route that checks access, streams `read(storageId)`, and sets `Content-Type`,
+  `Content-Disposition` and `X-Content-Type-Options: nosniff`.
+- In Next.js, import the server entry from a module that starts with `import "server-only"`, so it can't end up in a
+  client bundle. The package doesn't import `server-only` itself, so it works in any Node app.
+
+## Recipes
+
+**Allow a File category**
+
+```ts
+import {
+  getExtensionsByCategory,
+  getMimeTypesByCategory,
+} from "@rezwanul7/storage";
+
+const rules: ServerValidationRules = {
+  maxFileSize: "10MB",
+  allowedExtensions: getExtensionsByCategory("Spreadsheet"),
+  allowedMimeTypes: getMimeTypesByCategory("Spreadsheet"),
+};
+```
+
+Categories matched by MIME prefix only, such as `"Image"`, have no exact MIME list: `getMimeTypesByCategory` throws for
+them. List the MIME types yourself.
+
+**Store several files**: all or nothing. Errors are keyed by the file's index.
+
+```ts
+const result = await uploader.store(files, rules, { directory: "imports" });
+if (!result.ok) {
+  // {1: ["File exceeds maximum size of 10.0 MB."]}
+  const fieldErrors = Object.fromEntries(
+    Object.entries(result.errors).map(([i, messages]) => [
+      `files.${i}`,
+      messages,
+    ]),
+  );
+}
+```
+
+**Read, serve or delete a stored file**
+
+```ts
+const storage = createStorage(row.provider);
+const file = await storage.read(row.storageId); // {stream, size}, or null if nothing is stored there
+await storage.delete(row.storageId);
+```
+
+**Add your own check**: return a message to reject the file, or nothing to accept it.
+
+```ts
+customValidators: [
+  ({ detectedMime, size }) =>
+    detectedMime === "image/png" && size > 5 * 1024 * 1024 ? "PNG images can't exceed 5MB." : undefined,
+],
+```
+
+## Results and errors
+
+`store` has two kinds of failure:
+
+- **The files break the Rules**: it returns `{ok: false, errors}` and stores nothing. The messages are safe to show.
+- **The Provider fails**: it deletes the files it already stored and throws a `StorageError`. Its message is for your
+  logs; show your own.
+
+| `code`                  | When                                                                | What to do                                |
+| ----------------------- | ------------------------------------------------------------------- | ----------------------------------------- |
+| `STORAGE_UPLOAD_FAILED` | The Storage couldn't store a file; `cause` is the Provider's error  | Tell the user to try again; log the error |
+| `STORAGE_INVALID_ID`    | A Storage ID points outside the Provider: bad data or a tampered ID | Treat the file as missing, and log it     |
+
+Map `StorageError` to your app's error types where you call the package, because the same failure can mean different
+things in different places:
+
+```ts
+const result = await uploader
+  .store(file, rules, { directory })
+  .catch((error) => {
+    if (error instanceof StorageError)
+      throw new MyAppError("The file couldn't be stored. Try again.", {
+        cause: error,
+      });
+    throw error;
+  });
+```
+
+## What uploads are checked for
+
+`store` reads each file's bytes and rejects it when:
+
+- its type can't be identified from its content, name or declared type;
+- its name or declared MIME type doesn't match its content (a renamed executable);
+- it is an executable or script, whatever the Rules allow;
+- its content has no recognisable signature (typically text) and still holds binary data, or isn't valid JSON or
+  JSONL for those extensions;
+- it breaks the Rules: size, allowed or blocked MIME types and extensions, then your own checks, in that order.
+
+The stored file's `mime` and `ext` are what the bytes say, not what the browser declared.
+
+## Adding a Provider
+
+1. Implement `FileStorage` with its own `provider` name. Pick each file's key under the given `directory`, and take
+   settings, including the Provider's client, as constructor options.
+2. Throw `StorageError("STORAGE_INVALID_ID", …)` for a Storage ID outside the Provider.
+3. Add it to your app's factory. Keep the existing Storages there, so files stored with them stay readable.
+
+## API reference
+
+Every export, parameter, and default is listed in the [API reference](./docs/api/README.md), generated from the source.
+
+## License
+
+MIT License. See [LICENSE](./LICENSE) for details.

package/dist/fileRules.types-CGXBnwzd.d.cts

@@ -0,0 +1,11 @@
+/** The size and extension Rules that both the browser-side zod schemas and the server check. */
+interface SharedFileRules {
+    /** Largest size allowed: bytes, or a size such as `"10MB"`. */
+    maxFileSize?: number | string;
+    /** Smallest size allowed: bytes, or a size such as `"1KB"`. */
+    minFileSize?: number | string;
+    /** Extensions allowed, lower case and without the dot. Any is allowed when omitted. */
+    allowedExtensions?: string[];
+}
+
+export type { SharedFileRules as S };

package/dist/fileRules.types-CGXBnwzd.d.ts

@@ -0,0 +1,11 @@
+/** The size and extension Rules that both the browser-side zod schemas and the server check. */
+interface SharedFileRules {
+    /** Largest size allowed: bytes, or a size such as `"10MB"`. */
+    maxFileSize?: number | string;
+    /** Smallest size allowed: bytes, or a size such as `"1KB"`. */
+    minFileSize?: number | string;
+    /** Extensions allowed, lower case and without the dot. Any is allowed when omitted. */
+    allowedExtensions?: string[];
+}
+
+export type { SharedFileRules as S };