@byline/storage-local 1.6.2 → 1.7.1

package/dist/local-storage-provider.d.ts

@@ -11,7 +11,14 @@ export interface LocalStorageConfig {
      * Absolute or project-relative path to the root directory where uploaded
      * files will be stored.
      *
-     * @example `'./public/uploads'`
+     * For TanStack Start + Nitro hosts, keep this OUTSIDE `public/` — anything
+     * under `public/` is snapshotted into `.output/public/` at build time and
+     * served by Nitro's static handler from that snapshot, so files written at
+     * runtime won't appear until the next rebuild. Pair `uploadDir` with a
+     * runtime handler in your server entry that streams from this directory
+     * on every request.
+     *
+     * @example `'./uploads'`
      */
     uploadDir: string;
     /**
@@ -30,10 +37,18 @@ export interface LocalStorageConfig {
  *   `<collection>/<year>/<month>/<uuid>-<filename>`
  *
  * The provider generates a public URL by prepending `baseUrl` to the
- * storage path. Pair this with a static file server (e.g. Express
- * `express.static`, TanStack Start's static file serving, or nginx) that
+ * storage path. Pair this with a runtime file handler (Express
+ * `express.static`, an h3 handler, an nginx location block, or a small
+ * `Request → Response` shim in your TanStack Start `server.ts`) that
  * serves the `uploadDir` directory at the `baseUrl` path.
  *
+ * On TanStack Start + Nitro, do NOT use `nitro.publicAssets` for this:
+ * `publicAssets` copies into `.output/public/<baseURL>/` at build time
+ * and the Nitro static handler reads from a build-time virtual asset
+ * registry, so files written after the build never resolve. Use a
+ * runtime handler in `src/server.ts` instead — see the host scaffold
+ * shipped by `@byline/cli` for a worked example.
+ *
  * @example
  * ```ts
  * import { localStorageProvider } from '@byline/storage-local'
@@ -43,7 +58,7 @@ export interface LocalStorageConfig {
  *   ...config,
  *   db: pgAdapter({ connectionString: process.env.DB_CONNECTION_STRING! }),
  *   storage: localStorageProvider({
- *     uploadDir: './public/uploads',
+ *     uploadDir: './uploads',
  *     baseUrl: '/uploads',
  *   }),
  * })

package/dist/local-storage-provider.js

@@ -97,10 +97,18 @@ class LocalStorageProvider {
  *   `<collection>/<year>/<month>/<uuid>-<filename>`
  *
  * The provider generates a public URL by prepending `baseUrl` to the
- * storage path. Pair this with a static file server (e.g. Express
- * `express.static`, TanStack Start's static file serving, or nginx) that
+ * storage path. Pair this with a runtime file handler (Express
+ * `express.static`, an h3 handler, an nginx location block, or a small
+ * `Request → Response` shim in your TanStack Start `server.ts`) that
  * serves the `uploadDir` directory at the `baseUrl` path.
  *
+ * On TanStack Start + Nitro, do NOT use `nitro.publicAssets` for this:
+ * `publicAssets` copies into `.output/public/<baseURL>/` at build time
+ * and the Nitro static handler reads from a build-time virtual asset
+ * registry, so files written after the build never resolve. Use a
+ * runtime handler in `src/server.ts` instead — see the host scaffold
+ * shipped by `@byline/cli` for a worked example.
+ *
  * @example
  * ```ts
  * import { localStorageProvider } from '@byline/storage-local'
@@ -110,7 +118,7 @@ class LocalStorageProvider {
  *   ...config,
  *   db: pgAdapter({ connectionString: process.env.DB_CONNECTION_STRING! }),
  *   storage: localStorageProvider({
- *     uploadDir: './public/uploads',
+ *     uploadDir: './uploads',
  *     baseUrl: '/uploads',
  *   }),
  * })

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/storage-local",
   "private": false,
   "license": "MPL-2.0",
-  "version": "1.6.2",
+  "version": "1.7.1",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -40,7 +40,7 @@
   "dependencies": {
     "npm-run-all": "^4.1.5",
     "uuid": "^14.0.0",
-    "@byline/core": "1.6.2"
+    "@byline/core": "1.7.1"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.14",

package/dist/image-processor.d.ts

@@ -1,44 +0,0 @@
-/**
- * This Source Code is subject to the terms of the Mozilla Public
- * License, v. 2.0. If a copy of the MPL was not distributed with this
- * file, You can obtain one at http://mozilla.org/MPL/2.0/.
- *
- * Copyright (c) Infonomic Company Limited
- */
-import type { BylineLogger, ImageSize } from '@byline/core';
-export interface ImageMeta {
-    width: number | null;
-    height: number | null;
-    format: string | null;
-}
-export interface ImageVariantResult {
-    name: string;
-    storagePath: string;
-    width: number | undefined;
-    height: number | undefined;
-    format: string;
-}
-export interface ProcessImageResult {
-    meta: ImageMeta;
-    variants: ImageVariantResult[];
-}
-/**
- * Returns true for MIME types that should skip Sharp processing.
- * SVGs are vector files — Sharp cannot meaningfully resize or convert them,
- * and they do not benefit from the responsive-image pipeline.
- */
-export declare function isBypassMimeType(mimeType: string): boolean;
-/**
- * Extract basic image metadata (dimensions + format) from a buffer using Sharp.
- * Returns nulls for non-image or unrecognised formats.
- */
-export declare function extractImageMeta(buffer: Buffer, mimeType: string): Promise<ImageMeta>;
-/**
- * Generate the named image variants (sizes) defined in `UploadConfig.sizes`.
- *
- * - SVG and GIF files are skipped entirely (bypass types).
- * - Each variant is written as a sibling file to the original, using the
- *   naming convention: `<basename>-<variantName>.<ext>`
- * - Returns an array of `ImageVariantResult` describing what was created.
- */
-export declare function generateImageVariants(sourceBuffer: Buffer, mimeType: string, absoluteOriginalPath: string, storageBaseDir: string, sizes: ImageSize[], logger?: BylineLogger): Promise<ImageVariantResult[]>;

package/dist/image-processor.js

@@ -1,138 +0,0 @@
-/**
- * This Source Code is subject to the terms of the Mozilla Public
- * License, v. 2.0. If a copy of the MPL was not distributed with this
- * file, You can obtain one at http://mozilla.org/MPL/2.0/.
- *
- * Copyright (c) Infonomic Company Limited
- */
-import fs from 'node:fs';
-import path from 'node:path';
-// Sharp ships its own types; no @types/sharp needed.
-import sharp from 'sharp';
-// ---------------------------------------------------------------------------
-// SVG detection
-// ---------------------------------------------------------------------------
-/**
- * Returns true for MIME types that should skip Sharp processing.
- * SVGs are vector files — Sharp cannot meaningfully resize or convert them,
- * and they do not benefit from the responsive-image pipeline.
- */
-export function isBypassMimeType(mimeType) {
-    return mimeType === 'image/svg+xml' || mimeType === 'image/gif';
-}
-// ---------------------------------------------------------------------------
-// Metadata extraction
-// ---------------------------------------------------------------------------
-/**
- * Extract basic image metadata (dimensions + format) from a buffer using Sharp.
- * Returns nulls for non-image or unrecognised formats.
- */
-export async function extractImageMeta(buffer, mimeType) {
-    if (isBypassMimeType(mimeType)) {
-        // For SVGs, attempt a lightweight XML parse for width/height attributes.
-        const svgMeta = tryParseSvgDimensions(buffer);
-        return { width: svgMeta.width, height: svgMeta.height, format: 'svg' };
-    }
-    try {
-        const metadata = await sharp(buffer).metadata();
-        return {
-            width: metadata.width ?? null,
-            height: metadata.height ?? null,
-            format: metadata.format ?? null,
-        };
-    }
-    catch {
-        return { width: null, height: null, format: null };
-    }
-}
-/**
- * A lightweight SVG width/height parser — avoids pulling in a full XML library.
- * Only reads the root `<svg>` element's `width` and `height` attributes.
- */
-function tryParseSvgDimensions(buffer) {
-    try {
-        const text = buffer.toString('utf8', 0, Math.min(buffer.length, 2048));
-        const widthMatch = text.match(/<svg[^>]*\swidth=["']([0-9.]+)(?:px)?["']/);
-        const heightMatch = text.match(/<svg[^>]*\sheight=["']([0-9.]+)(?:px)?["']/);
-        return {
-            width: widthMatch ? Math.round(Number.parseFloat(widthMatch[1])) : null,
-            height: heightMatch ? Math.round(Number.parseFloat(heightMatch[1])) : null,
-        };
-    }
-    catch {
-        return { width: null, height: null };
-    }
-}
-// ---------------------------------------------------------------------------
-// Variant generation
-// ---------------------------------------------------------------------------
-/**
- * Generate the named image variants (sizes) defined in `UploadConfig.sizes`.
- *
- * - SVG and GIF files are skipped entirely (bypass types).
- * - Each variant is written as a sibling file to the original, using the
- *   naming convention: `<basename>-<variantName>.<ext>`
- * - Returns an array of `ImageVariantResult` describing what was created.
- */
-export async function generateImageVariants(sourceBuffer, mimeType, absoluteOriginalPath, storageBaseDir, sizes, logger) {
-    if (isBypassMimeType(mimeType) || sizes.length === 0) {
-        return [];
-    }
-    const originalExt = path.extname(absoluteOriginalPath);
-    const originalBase = path.basename(absoluteOriginalPath, originalExt);
-    const variantDir = path.dirname(absoluteOriginalPath);
-    const variants = [];
-    for (const size of sizes) {
-        const outputFormat = size.format ?? 'webp';
-        const outputExt = `.${outputFormat}`;
-        const variantFilename = `${originalBase}-${size.name}${outputExt}`;
-        const variantAbsolutePath = path.join(variantDir, variantFilename);
-        // Derive the storage-relative path (relative to storageBaseDir).
-        const variantStoragePath = path
-            .relative(storageBaseDir, variantAbsolutePath)
-            .replace(/\\/g, '/');
-        try {
-            let pipeline = sharp(sourceBuffer);
-            const resizeOptions = {
-                width: size.width,
-                height: size.height,
-                fit: size.fit ?? 'cover',
-                withoutEnlargement: true,
-            };
-            pipeline = pipeline.resize(resizeOptions);
-            // Apply format + quality.
-            switch (outputFormat) {
-                case 'jpeg':
-                    pipeline = pipeline.jpeg({ quality: size.quality ?? 85 });
-                    break;
-                case 'png':
-                    pipeline = pipeline.png({ quality: size.quality ?? 85 });
-                    break;
-                case 'webp':
-                    pipeline = pipeline.webp({ quality: size.quality ?? 85 });
-                    break;
-                case 'avif':
-                    pipeline = pipeline.avif({ quality: size.quality ?? 55 });
-                    break;
-                default:
-                    pipeline = pipeline.webp({ quality: size.quality ?? 85 });
-            }
-            const variantBuffer = await pipeline.toBuffer();
-            fs.mkdirSync(path.dirname(variantAbsolutePath), { recursive: true });
-            await fs.promises.writeFile(variantAbsolutePath, variantBuffer);
-            const sharpMeta = await sharp(variantBuffer).metadata();
-            variants.push({
-                name: size.name,
-                storagePath: variantStoragePath,
-                width: sharpMeta.width,
-                height: sharpMeta.height,
-                format: outputFormat,
-            });
-        }
-        catch (err) {
-            logger?.error({ err, variant: size.name }, 'failed to generate image variant');
-            // Non-fatal: skip this variant but continue with others.
-        }
-    }
-    return variants;
-}