@zintrust/storage 0.1.27

package/README.md

@@ -0,0 +1,25 @@
+# @zintrust/storage
+
+Core storage (disk driver) abstraction for ZinTrust with multipart form parsing support.
+
+- Docs: https://zintrust.com/storage
+
+## Install
+
+```bash
+npm i @zintrust/storage
+```
+
+## Usage
+
+Register storage drivers at startup:
+
+```ts
+import '@zintrust/storage/register';
+```
+
+Then configure storage disks and use `Storage` to interact with drivers.
+
+## License
+
+This package and its dependencies are MIT licensed, permitting free commercial use.

package/dist/build-manifest.json

@@ -0,0 +1,55 @@
+{
+  "name": "@zintrust/storage",
+  "version": "0.1.19",
+  "buildDate": "2026-01-28T12:31:13.892Z",
+  "buildEnvironment": {
+    "node": "v22.20.0",
+    "platform": "darwin",
+    "arch": "arm64"
+  },
+  "git": {
+    "commit": "2d1585bf",
+    "branch": "dev"
+  },
+  "package": {
+    "engines": {
+      "node": ">=20.0.0"
+    },
+    "dependencies": [
+      "busboy"
+    ],
+    "peerDependencies": [
+      "@zintrust/core"
+    ]
+  },
+  "files": {
+    "build-manifest.json": {
+      "size": 1416,
+      "sha256": "aaa9b782b10341a8568819bed53b81979529e8404debd57402f2747cd888c890"
+    },
+    "index.d.ts": {
+      "size": 484,
+      "sha256": "f34f75d41253ceea8da492ff343a0e18b458f54be00e1a83c1f76f86d0baf24e"
+    },
+    "index.js": {
+      "size": 486,
+      "sha256": "01fb41ef99a9d83ec7d715c3644394e22ad06a596875c8e1e44e9dbbd4273ffa"
+    },
+    "register.d.ts": {
+      "size": 178,
+      "sha256": "2a1118ead443b7146d48400a425197511d5e97ede5a080993609a6533a604594"
+    },
+    "register.js": {
+      "size": 87,
+      "sha256": "03abea656f44f29f5905140258f0a0a457a2f08d5ab07bc59be93fc7ef94f427"
+    },
+    "registerStreamingMultipartParser.d.ts": {
+      "size": 372,
+      "sha256": "7b599c14cc4bed64dbbeb89da8e8161ea553de660d9bb1041eb02d84722fa3ef"
+    },
+    "registerStreamingMultipartParser.js": {
+      "size": 6432,
+      "sha256": "c9146380136edd8e2697e0e67e67136b789c7505b543a45dd1c97f81bf39f97c"
+    }
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export type { MultipartFieldValue, MultipartParseInput, MultipartParserProvider, ParsedMultipartData, } from '@zintrust/core';
+export { registerStreamingMultipartParser, type StreamingMultipartParserOptions, } from './registerStreamingMultipartParser';
+/**
+ * Package version and build metadata
+ * Available at runtime for debugging and health checks
+ */
+export declare const _ZINTRUST_STORAGE_VERSION = "0.1.19";
+export declare const _ZINTRUST_STORAGE_BUILD_DATE = "__BUILD_DATE__";

package/dist/index.js

@@ -0,0 +1,7 @@
+export { registerStreamingMultipartParser, } from './registerStreamingMultipartParser';
+/**
+ * Package version and build metadata
+ * Available at runtime for debugging and health checks
+ */
+export const _ZINTRUST_STORAGE_VERSION = '0.1.19';
+export const _ZINTRUST_STORAGE_BUILD_DATE = '__BUILD_DATE__';

package/dist/register.d.ts

@@ -0,0 +1,2 @@
+export { registerStreamingMultipartParser } from './registerStreamingMultipartParser';
+export type { StreamingMultipartParserOptions } from './registerStreamingMultipartParser';

package/dist/register.js

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

package/dist/registerStreamingMultipartParser.d.ts

@@ -0,0 +1,12 @@
+export type StreamingMultipartParserOptions = {
+    /**
+     * Where uploaded files are buffered.
+     * Defaults to `os.tmpdir()/zintrust/uploads`.
+     */
+    tmpDir?: string;
+    /**
+     * Prefix for generated filenames.
+     */
+    filenamePrefix?: string;
+};
+export declare function registerStreamingMultipartParser(options?: StreamingMultipartParserOptions): void;

package/dist/registerStreamingMultipartParser.js

@@ -0,0 +1,199 @@
+import { MultipartParserRegistry, NodeSingletons, } from '@zintrust/core';
+import Busboy from 'busboy';
+const defaultTmpDir = () => NodeSingletons.path.join(NodeSingletons.os.tmpdir(), 'zintrust', 'uploads');
+const ensureDir = async (dir) => {
+    await NodeSingletons.fs.fsPromises.mkdir(dir, { recursive: true });
+};
+const safeUnlink = async (filePath) => {
+    try {
+        await NodeSingletons.fs.fsPromises.unlink(filePath);
+    }
+    catch {
+        // best-effort
+    }
+};
+const addFieldValue = (fields, name, value) => {
+    const existing = fields[name];
+    if (existing === undefined) {
+        fields[name] = value;
+        return;
+    }
+    if (Array.isArray(existing)) {
+        existing.push(value);
+        return;
+    }
+    fields[name] = [existing, value];
+};
+const makeTmpFilename = (input) => {
+    // Avoid trusting originalName for filesystem paths.
+    const uuid = typeof globalThis?.crypto?.randomUUID === 'function'
+        ? globalThis.crypto.randomUUID()
+        : NodeSingletons.randomBytes(16).toString('hex');
+    const base = `${input.prefix}${uuid}`;
+    const ext = (() => {
+        const normalized = input.originalName.trim();
+        const idx = normalized.lastIndexOf('.');
+        if (idx <= 0)
+            return '';
+        const raw = normalized.slice(idx).toLowerCase();
+        // Keep extension length bounded.
+        if (raw.length > 12)
+            return '';
+        if (!/^[.][a-z0-9]+$/.test(raw))
+            return '';
+        return raw;
+    })();
+    return `${base}${ext}`;
+};
+const handleFileUpload = (fieldName, fileStream, info, ctx) => {
+    const originalName = info.filename ?? '';
+    const mimeType = info.mimeType ?? 'application/octet-stream';
+    const encoding = info.encoding;
+    const filename = makeTmpFilename({
+        prefix: ctx.opts.filenamePrefix,
+        originalName,
+    });
+    const tmpPath = NodeSingletons.path.join(ctx.opts.tmpDir, filename);
+    ctx.createdPaths.add(tmpPath);
+    const writeStream = NodeSingletons.fs.createWriteStream(tmpPath, { flags: 'wx' });
+    let size = 0;
+    const sha256 = NodeSingletons.createHash('sha256');
+    fileStream.on('data', (chunk) => {
+        size += chunk.length;
+        sha256.update(chunk);
+    });
+    fileStream.on('limit', () => {
+        fileStream.unpipe(writeStream);
+        try {
+            writeStream.destroy();
+        }
+        catch {
+            // best-effort
+        }
+        ctx.rejectOnce(new Error('File too large'));
+    });
+    writeStream.on('error', (err) => {
+        ctx.rejectOnce(err);
+    });
+    const uploadedFile = {
+        fieldName,
+        originalName,
+        mimeType,
+        encoding,
+        size: 0,
+        path: tmpPath,
+        stream: () => NodeSingletons.fs.createReadStream(tmpPath),
+        cleanup: async () => {
+            await safeUnlink(tmpPath);
+            ctx.createdPaths.delete(tmpPath);
+        },
+    };
+    ctx.files[fieldName] ??= [];
+    ctx.files[fieldName]?.push(uploadedFile);
+    writeStream.on('close', () => {
+        uploadedFile.size = size;
+        // Expose hash for advanced validation without reading into memory.
+        uploadedFile.sha256 = sha256.digest('hex');
+    });
+    fileStream.pipe(writeStream);
+};
+const setupBusboyHandlers = (bb, ctx) => {
+    bb.on('field', (name, value) => {
+        addFieldValue(ctx.fields, name, value);
+    });
+    bb.on('file', (fieldName, fileStream, info) => {
+        handleFileUpload(fieldName, fileStream, info, ctx);
+    });
+    bb.on('filesLimit', () => ctx.rejectOnce(new Error('Too many files')));
+    bb.on('fieldsLimit', () => ctx.rejectOnce(new Error('Too many fields')));
+    bb.on('partsLimit', () => ctx.rejectOnce(new Error('Too many parts')));
+    bb.on('error', (err) => ctx.rejectOnce(err));
+};
+const createBusboyInstance = (input) => {
+    return Busboy({
+        headers: input.req.headers,
+        limits: {
+            fileSize: input.limits.maxFileSizeBytes,
+            files: input.limits.maxFiles,
+            fields: input.limits.maxFields,
+            fieldSize: input.limits.maxFieldSizeBytes,
+        },
+    });
+};
+const createSettlementHandlers = (createdPaths) => {
+    let settled = false;
+    const cleanupAll = async () => {
+        await Promise.allSettled(Array.from(createdPaths).map((p) => safeUnlink(p)));
+    };
+    return {
+        resolveOnce: (value, resolve) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(value);
+        },
+        rejectOnce: (err, reject) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanupAll()
+                .finally(() => reject(err))
+                .catch(() => {
+                // Ignore cleanup errors during rejection
+            });
+        },
+        isSettled: () => settled,
+    };
+};
+const executeParsing = (input, opts, fields, files, createdPaths, resolve, reject) => {
+    let finished = false;
+    const settlement = createSettlementHandlers(createdPaths);
+    const resolveOnce = (value) => {
+        settlement.resolveOnce(value, resolve);
+    };
+    const rejectOnce = (err) => {
+        settlement.rejectOnce(err, reject);
+    };
+    const bb = createBusboyInstance(input);
+    const onAbortOrClose = () => {
+        if (finished)
+            return;
+        rejectOnce(new Error('Upload aborted'));
+    };
+    input.req.once('aborted', onAbortOrClose);
+    input.req.once('close', onAbortOrClose);
+    const ctx = {
+        fields,
+        files,
+        createdPaths,
+        finished: false,
+        rejectOnce,
+        opts,
+    };
+    setupBusboyHandlers(bb, ctx);
+    bb.on('finish', () => {
+        finished = true;
+        ctx.finished = true;
+        resolveOnce({ fields, files });
+    });
+    try {
+        input.req.pipe(bb);
+    }
+    catch (err) {
+        rejectOnce(err);
+    }
+};
+const parseWithBusboy = async (input, opts) => {
+    await ensureDir(opts.tmpDir);
+    const fields = {};
+    const files = {};
+    const createdPaths = new Set();
+    return new Promise((resolve, reject) => {
+        executeParsing(input, opts, fields, files, createdPaths, resolve, reject);
+    });
+};
+export function registerStreamingMultipartParser(options = {}) {
+    const tmpDir = options.tmpDir ?? defaultTmpDir();
+    const filenamePrefix = options.filenamePrefix ?? 'upload-';
+    MultipartParserRegistry.register((input) => parseWithBusboy(input, { tmpDir, filenamePrefix }));
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@zintrust/storage",
+  "version": "0.1.27",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./register": {
+      "types": "./dist/register.d.ts",
+      "default": "./dist/register.js"
+    }
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "peerDependencies": {
+    "@zintrust/core": "^0.1.27"
+  },
+  "dependencies": {
+    "busboy": "^1.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  }
+}