@stacksjs/storage 0.74.41 → 0.74.42

package/dist/file-info.d.ts

@@ -0,0 +1,52 @@
+/** The presentation category for a mime type. */
+export declare function fileKind(mime: string): FileKind;
+/**
+ * Whether a preview can be rendered from the bytes alone.
+ *
+ * `false` does not mean "no preview is possible" - it means one cannot be made
+ * here, without a transcoder, a renderer or a headless browser. A caller that
+ * has those can still produce one; the point is that this module does not
+ * pretend it did.
+ *
+ * SVG is excluded from previewable despite being an image: rendering
+ * attacker-supplied SVG is script execution, and the decision to do it anyway
+ * belongs to the caller who knows where the file came from.
+ */
+export declare function isPreviewable(mime: string): boolean;
+/** Resolve the mime type from bytes first, then the name. */
+export declare function resolveMime(bytes: Uint8Array, name?: string): { mime: string, source: FileInfo['mimeSource'] };
+/**
+ * Describe a file from its bytes.
+ *
+ * `name` is optional and used only for the extension fallback, so this works
+ * for an in-memory upload that has no path yet.
+ *
+ * Image metadata is read through `ts-images`, imported lazily: a caller asking
+ * about a PDF should not pay to load an image decoder. A decode failure is not
+ * an error - a truncated or malformed image is still a file with a size and a
+ * type, and returning that beats throwing on the one case a file manager most
+ * needs to display.
+ */
+export declare function fileInfoFromBytes(bytes: Uint8Array, name?: string): Promise<FileInfo>;
+/** Describe a file on disk. */
+export declare function fileInfo(path: string): Promise<FileInfo>;
+export declare interface FileInfo {
+  mime: string
+  mimeSource: 'magic-bytes' | 'extension' | 'fallback'
+  size: number
+  kind: FileKind
+  previewable: boolean
+  image?: ImageInfo
+}
+/** What `ts-images` reports about a decoded image. */
+export declare interface ImageInfo {
+  width: number
+  height: number
+  format: string
+  channels?: number
+  bitDepth?: number
+  hasAlpha?: boolean
+  colorSpace?: string
+}
+/** What a UI branches on: how to present the file, not what encodes it. */
+export type FileKind = 'image' | 'video' | 'audio' | 'pdf' | 'text' | 'archive' | 'font' | 'other';

package/dist/file-info.js

@@ -0,0 +1 @@
+import{extname}from"node:path";import{detectMimeFromMagicBytes}from"./mime-verify";const EXTENSION_MIME={".txt":"text/plain",".md":"text/markdown",".csv":"text/csv",".json":"application/json",".xml":"application/xml",".svg":"image/svg+xml",".html":"text/html",".css":"text/css",".js":"text/javascript",".ts":"text/typescript",".yaml":"application/yaml",".yml":"application/yaml"},KIND_BY_TYPE=[[/^image\//,"image"],[/^video\//,"video"],[/^audio\//,"audio"],[/^font\/|^application\/(?:x-)?font/,"font"],[/^application\/pdf$/,"pdf"],[/^application\/(?:zip|x-tar|gzip|x-7z|x-rar|x-bzip)/,"archive"],[/^text\/|^application\/(?:json|xml|yaml|javascript|typescript)/,"text"]];export function fileKind(mime){for(const[pattern,kind]of KIND_BY_TYPE)if(pattern.test(mime))return kind;return"other"}export function isPreviewable(mime){if(mime==="image/svg+xml")return!1;return fileKind(mime)==="image"||fileKind(mime)==="text"}export function resolveMime(bytes,name){const sniffed=detectMimeFromMagicBytes(bytes);if(sniffed)return{mime:sniffed,source:"magic-bytes"};if(name){const byExtension=EXTENSION_MIME[extname(name).toLowerCase()];if(byExtension)return{mime:byExtension,source:"extension"}}return{mime:"application/octet-stream",source:"fallback"}}export async function fileInfoFromBytes(bytes,name){const{mime,source}=resolveMime(bytes,name),kind=fileKind(mime),info={mime,mimeSource:source,size:bytes.byteLength,kind,previewable:isPreviewable(mime)};if(kind==="image"&&mime!=="image/svg+xml")try{const{getMetadata}=await import("ts-images");info.image=await getMetadata(bytes)}catch{}return info}export async function fileInfo(path){const file=Bun.file(path),bytes=new Uint8Array(await file.arrayBuffer());return fileInfoFromBytes(bytes,path)}

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export type { DiskName, KnownDisks } from './types/filesystem';
 export type { SignedTokenVerification } from './signed-url';
 export type { SignedUrlOptions } from './types';
 export type { ParsedDiskPath } from './path-sanitize';
+export type { FileInfo, FileKind, ImageInfo } from './file-info';
 export type { MimeVerifyResult } from './mime-verify';
 export type { S3PresignedPostInput, S3PresignedPostResult } from './s3-presigned-post';
 export type {
@@ -54,6 +55,7 @@ export { parseDiskPath, PathSanitizeError, sanitizePresignedDir, sanitizePresign
 // MIME re-verification — server-side check that uploaded bytes match
 // the claimed content type. Run this after a presigned upload
 // completes since `Content-Type` on a presigned PUT is caller-attested.
+export { fileInfo, fileInfoFromBytes, fileKind, isPreviewable, resolveMime } from './file-info';
 export { detectMimeFromMagicBytes, verifyUploadedMime } from './mime-verify';
 // S3 presigned-POST policy signer (stacksjs/stacks#1888 Phase B).
 // Exposed as a standalone for callers that have their own S3 client

package/dist/index.js

@@ -1 +1 @@
-export*from"./copy";export*from"./delete";export*from"./files";export*from"./folders";export*from"./fs";export*from"./glob";export*from"./hash";export*from"./helpers";export* as storage from"./storage";export*from"./zip";export{ensureBucket,ensureConfiguredBuckets}from"./provision";export*from"./adapters";export*from"./types";export*from"./drivers";export{serveFile}from"./static-serve";export{Storage,StorageManager}from"./facade";export{UploadedFile,uploadedFile,uploadedFiles}from"./uploaded-file";export{azureDisk,backblazeDisk,configFromEnv,filebaseDisk,gcsDisk,hetznerDisk,localDisk,r2Disk,s3Disk}from"./types/filesystem";export{clearRevokedSignedStorageTokens,createSignedStorageToken,isSignedStorageTokenRevoked,revokeSignedStorageToken,verifySignedStorageToken}from"./signed-url";export{parseDiskPath,PathSanitizeError,sanitizePresignedDir,sanitizePresignedFilename}from"./path-sanitize";export{detectMimeFromMagicBytes,verifyUploadedMime}from"./mime-verify";export{signS3PresignedPost}from"./s3-presigned-post";
+export*from"./copy";export*from"./delete";export*from"./files";export*from"./folders";export*from"./fs";export*from"./glob";export*from"./hash";export*from"./helpers";export* as storage from"./storage";export*from"./zip";export{ensureBucket,ensureConfiguredBuckets}from"./provision";export*from"./adapters";export*from"./types";export*from"./drivers";export{serveFile}from"./static-serve";export{Storage,StorageManager}from"./facade";export{UploadedFile,uploadedFile,uploadedFiles}from"./uploaded-file";export{azureDisk,backblazeDisk,configFromEnv,filebaseDisk,gcsDisk,hetznerDisk,localDisk,r2Disk,s3Disk}from"./types/filesystem";export{clearRevokedSignedStorageTokens,createSignedStorageToken,isSignedStorageTokenRevoked,revokeSignedStorageToken,verifySignedStorageToken}from"./signed-url";export{parseDiskPath,PathSanitizeError,sanitizePresignedDir,sanitizePresignedFilename}from"./path-sanitize";export{fileInfo,fileInfoFromBytes,fileKind,isPreviewable,resolveMime}from"./file-info";export{detectMimeFromMagicBytes,verifyUploadedMime}from"./mime-verify";export{signS3PresignedPost}from"./s3-presigned-post";

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/storage",
   "type": "module",
   "sideEffects": false,
-  "version": "0.74.41",
+  "version": "0.74.42",
   "description": "The Stacks file system.",
   "author": "Chris Breuer",
   "contributors": [
@@ -61,20 +61,20 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/arrays": "0.74.41",
-    "@stacksjs/cli": "0.74.41",
-    "@stacksjs/config": "0.74.41",
-    "@stacksjs/env": "0.74.41",
-    "@stacksjs/error-handling": "0.74.41",
-    "@stacksjs/logging": "0.74.41",
-    "@stacksjs/path": "0.74.41",
-    "@stacksjs/strings": "0.74.41",
+    "@stacksjs/arrays": "0.74.42",
+    "@stacksjs/cli": "0.74.42",
+    "@stacksjs/config": "0.74.42",
+    "@stacksjs/env": "0.74.42",
+    "@stacksjs/error-handling": "0.74.42",
+    "@stacksjs/logging": "0.74.42",
+    "@stacksjs/path": "0.74.42",
+    "@stacksjs/strings": "0.74.42",
     "@stacksjs/ts-cloud": "^0.16.0",
     "@stacksjs/ts-xml": "^0.1.0",
     "ts-images": "^0.2.11"
   },
   "devDependencies": {
-    "@stacksjs/types": "0.74.41",
+    "@stacksjs/types": "0.74.42",
     "better-dx": "^0.2.24"
   }
 }