@stacksjs/storage 0.70.88 → 0.70.91

package/dist/types.d.ts

@@ -0,0 +1,229 @@
+import type { Buffer } from 'node:buffer';
+/**
+ * Helper to create async iterable from array
+ */
+export declare function createDirectoryListing(entries: DirectoryEntry[]): DirectoryListing;
+/**
+ * Convert expiry to milliseconds
+ */
+export declare function normalizeExpiryToMilliseconds(expiry: number | Date): number;
+/**
+ * Convert expiry to Date
+ */
+export declare function normalizeExpiryToDate(expiry: number | Date): Date;
+/**
+ * Check if entry is a file
+ */
+export declare function isFile(entry: DirectoryEntry | StatEntry): boolean;
+/**
+ * Check if entry is a directory
+ */
+export declare function isDirectory(entry: DirectoryEntry | StatEntry): boolean;
+/**
+ * File stat entry information
+ */
+export declare interface StatEntry {
+  path: string
+  type: 'file' | 'directory'
+  visibility: Visibility
+  size: number
+  lastModified: number
+  mimeType?: string
+  metadata?: Record<string, any>
+}
+/**
+ * Options for `Storage.getStream(path, options?)`
+ * (stacksjs/stacks#1886).
+ */
+export declare interface GetStreamOptions {
+  signal?: AbortSignal
+}
+/**
+ * Options for `Storage.putStream(path, stream, options?)`
+ * (stacksjs/stacks#1886). All fields are optional; the S3 driver
+ * reads them to tune its multipart pipeline, other drivers
+ * generally only honor `contentType` and `signal`.
+ */
+export declare interface PutStreamOptions {
+  contentType?: string
+  signal?: AbortSignal
+  partSize?: number
+  concurrency?: number
+  maxRetries?: number
+}
+/**
+ * Result returned from `Storage.put()` (stacksjs/stacks#1888 S-8).
+ *
+ * Pre-fix `put()` returned `Promise<void>` — callers that wanted to
+ * record an etag for cache-invalidation or a size for storage-quota
+ * accounting had to issue a second `.stat()` round-trip. This shape
+ * carries the metadata back from the write itself.
+ *
+ * Fields beyond `path` are best-effort: drivers that don't expose
+ * (or can't cheaply compute) a value omit it rather than synthesizing
+ * a fake one. Callers should treat them as nullable.
+ */
+export declare interface PutResult {
+  path: string
+  size: number
+  contentType?: string
+  lastModified?: number
+  etag?: string
+}
+/**
+ * Directory listing entry
+ */
+export declare interface DirectoryEntry {
+  path: string
+  type: 'file' | 'directory'
+}
+/**
+ * Directory listing iterator
+ */
+export declare interface DirectoryListing extends AsyncIterable<DirectoryEntry> {
+  [Symbol.asyncIterator](): AsyncIterator<DirectoryEntry>
+}
+/**
+ * Options for listing directories
+ */
+export declare interface ListOptions {
+  deep?: boolean
+}
+/**
+ * Options for generating public URLs
+ */
+export declare interface PublicUrlOptions {
+  domain?: string
+}
+/**
+ * Options for generating temporary URLs
+ */
+export declare interface TemporaryUrlOptions {
+  expiresIn: number | Date
+}
+/**
+ * Options for generating signed (JWT-style) URLs.
+ *
+ * Distinct from `TemporaryUrlOptions` so adapters that don't natively
+ * support the richer claims set (in-memory mocks) can throw a clear
+ * "unsupported" error rather than silently returning a useless URL.
+ */
+export declare interface SignedUrlOptions {
+  expiresIn: number | Date
+  issuer?: string
+  baseUrl?: string
+}
+/**
+ * Options for `presignedUploadPolicy()` — the POST-form upload
+ * primitive that S3 can enforce server-side (stacksjs/stacks#1888
+ * Phase B). Distinct from {@link PresignedUploadUrlOptions} (PUT-
+ * form): the POST policy carries a `Content-Length-Range` condition
+ * that S3 enforces server-side, so this is the right primitive when
+ * you genuinely need a size cap against an untrusted client.
+ */
+export declare interface PresignedUploadPolicyOptions {
+  key: string | { startsWith: string }
+  contentType: string | { startsWith: string }
+  contentLengthRange?: { min: number, max: number }
+  acl?: 'private' | 'public-read' | 'public-read-write' | 'authenticated-read' | 'bucket-owner-read' | 'bucket-owner-full-control'
+  expiresIn: number
+  fields?: Record<string, string>
+}
+/**
+ * What the caller hands to the browser. Submit as
+ * `multipart/form-data` to `url` with every entry of `fields` as a
+ * form field, then the actual file LAST under the field name
+ * `'file'`. `key` is what the upload will land at — store on the
+ * domain record.
+ */
+export declare interface PresignedUploadPolicy {
+  url: string
+  fields: Record<string, string>
+  key: string
+}
+/**
+ * Options for `presignedUploadUrl()` (stacksjs/stacks#1856 Stage 6).
+ */
+export declare interface PresignedUploadUrlOptions {
+  contentType: string
+  expiresIn: number
+  dir?: string
+  filename?: string
+  maxBytes?: number
+}
+export declare interface PresignedUploadUrl {
+  url: string
+  path: string
+  key: string
+  contentType: string
+  maxBytes?: number
+}
+/**
+ * Checksum algorithm options
+ */
+export declare interface ChecksumOptions {
+  algorithm?: 'md5' | 'sha1' | 'sha256'
+}
+/**
+ * MIME type detection options
+ */
+export declare interface MimeTypeOptions {
+  useExtension?: boolean
+}
+/**
+ * Storage adapter configuration
+ */
+export declare interface StorageAdapterConfig {
+  root?: string
+  bucket?: string
+  region?: string
+  prefix?: string
+  credentials?: {
+    accessKeyId: string
+    secretAccessKey: string
+    sessionToken?: string
+  }
+}
+/**
+ * Base storage adapter interface
+ */
+export declare interface StorageAdapter {
+  write(path: string, contents: FileContents): Promise<PutResult>
+  read(path: string): Promise<FileContents>
+  readToString(path: string): Promise<string>
+  readToBuffer(path: string): Promise<Buffer>
+  readToUint8Array(path: string): Promise<Uint8Array>
+  deleteFile(path: string): Promise<void>
+  deleteDirectory(path: string): Promise<void>
+  createDirectory(path: string): Promise<void>
+  moveFile(from: string, to: string): Promise<void>
+  copyFile(from: string, to: string): Promise<void>
+  stat(path: string): Promise<StatEntry>
+  list(path: string, options?: ListOptions): DirectoryListing
+  changeVisibility(path: string, visibility: Visibility): Promise<void>
+  visibility(path: string): Promise<Visibility>
+  fileExists(path: string): Promise<boolean>
+  directoryExists(path: string): Promise<boolean>
+  publicUrl(path: string, options?: PublicUrlOptions): Promise<string>
+  temporaryUrl(path: string, options: TemporaryUrlOptions): Promise<string>
+  signedUrl?(path: string, options: SignedUrlOptions): Promise<string>
+  presignedUploadUrl?(options: PresignedUploadUrlOptions): Promise<PresignedUploadUrl>
+  presignedUploadPolicy?(options: PresignedUploadPolicyOptions): Promise<PresignedUploadPolicy>
+  getStream?(path: string, options?: GetStreamOptions): Promise<ReadableStream<Uint8Array>>
+  putStream?(path: string, stream: ReadableStream<Uint8Array>, options?: PutStreamOptions): Promise<PutResult>
+  checksum(path: string, options?: ChecksumOptions): Promise<string>
+  mimeType(path: string, options?: MimeTypeOptions): Promise<string>
+  lastModified(path: string): Promise<number>
+  fileSize(path: string): Promise<number>
+}
+/**
+ * File contents can be a string, Buffer, Uint8Array, or ReadableStream
+ */
+export type FileContents = string | Buffer | Uint8Array | ReadableStream;
+/**
+ * Visibility options for files
+ */
+export declare enum Visibility {
+  PUBLIC = 'public',
+  PRIVATE = 'private',
+}

package/dist/types.js

@@ -0,0 +1,25 @@
+export var Visibility;
+((Visibility) => {
+  Visibility.PUBLIC = "public";
+  Visibility.PRIVATE = "private";
+})(Visibility ||= {});
+export async function* createDirectoryListing(entries) {
+  for (const entry of entries)
+    yield entry;
+}
+export function normalizeExpiryToMilliseconds(expiry) {
+  if (expiry instanceof Date)
+    return expiry.getTime() - Date.now();
+  return expiry * 1000;
+}
+export function normalizeExpiryToDate(expiry) {
+  if (expiry instanceof Date)
+    return expiry;
+  return new Date(Date.now() + expiry * 1000);
+}
+export function isFile(entry) {
+  return entry.type === "file";
+}
+export function isDirectory(entry) {
+  return entry.type === "directory";
+}

package/dist/uploaded-file.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Create UploadedFile from native File
+ */
+export declare function uploadedFile(file: File): UploadedFile;
+/**
+ * Create multiple UploadedFiles from native Files
+ */
+export declare function uploadedFiles(files: File[]): UploadedFile[];
+export declare interface UploadedFileOptions {
+  hashName?: boolean
+}
+export declare class UploadedFile {
+  constructor(file: File);
+  get name(): string;
+  get extension(): string;
+  get mimeType(): string;
+  get size(): number;
+  get file(): File;
+  hashName(extension?: string): string;
+  arrayBuffer(): Promise<ArrayBuffer>;
+  bytes(): Promise<Uint8Array>;
+  text(): Promise<string>;
+  isValid(): boolean;
+  store(path?: string, disk?: string): Promise<string>;
+  storeAs(path: string, name: string, disk?: string): Promise<string>;
+  storePublicly(path?: string): Promise<string>;
+  storePubliclyAs(path: string, name: string): Promise<string>;
+  move(path: string, disk?: string): Promise<string>;
+  getClientOriginalName(): string;
+  getClientOriginalExtension(): string;
+  getClientMimeType(): string;
+  getSize(): string;
+  isOneOf(mimeTypes: string[]): boolean;
+  isImage(): boolean;
+  isVideo(): boolean;
+  isAudio(): boolean;
+  isPdf(): boolean;
+}

package/dist/uploaded-file.js

@@ -0,0 +1,114 @@
+import { basename, extname, join } from "node:path";
+import { Storage } from "./facade";
+
+export class UploadedFile {
+  _file;
+  _hashName = null;
+  constructor(file) {
+    this._file = file;
+  }
+  get name() {
+    return this._file.name;
+  }
+  get extension() {
+    return extname(this._file.name).slice(1).toLowerCase();
+  }
+  get mimeType() {
+    return this._file.type;
+  }
+  get size() {
+    return this._file.size;
+  }
+  get file() {
+    return this._file;
+  }
+  hashName(extension) {
+    if (!this._hashName) {
+      const hash = crypto.randomUUID().replace(/-/g, "").slice(0, 32), ext = extension || this.extension;
+      this._hashName = ext ? `${hash}.${ext}` : hash;
+    }
+    return this._hashName;
+  }
+  async arrayBuffer() {
+    return this._file.arrayBuffer();
+  }
+  async bytes() {
+    const buffer = await this._file.arrayBuffer();
+    return new Uint8Array(buffer);
+  }
+  async text() {
+    return this._file.text();
+  }
+  isValid() {
+    return this._file.size > 0;
+  }
+  async store(path = "", disk = "local") {
+    const filename = this.hashName(), fullPath = path ? join(path, filename) : filename, contents = await this.bytes();
+    await Storage.disk(disk).write(fullPath, contents);
+    return fullPath;
+  }
+  async storeAs(path, name, disk = "local") {
+    if (name.includes("..") || name.includes("/") || name.includes("\\"))
+      throw Error("Invalid filename: path traversal or directory separator detected");
+    const sanitizedName = basename(name), fullPath = path ? join(path, sanitizedName) : sanitizedName, contents = await this.bytes();
+    await Storage.disk(disk).write(fullPath, contents);
+    return fullPath;
+  }
+  async storePublicly(path = "") {
+    return this.store(path, "public");
+  }
+  async storePubliclyAs(path, name) {
+    return this.storeAs(path, name, "public");
+  }
+  async move(path, disk = "local") {
+    const contents = await this.bytes();
+    await Storage.disk(disk).write(path, contents);
+    return path;
+  }
+  getClientOriginalName() {
+    return basename(this._file.name, extname(this._file.name));
+  }
+  getClientOriginalExtension() {
+    return this.extension;
+  }
+  getClientMimeType() {
+    return this._file.type;
+  }
+  getSize() {
+    const bytes = this._file.size;
+    if (bytes < 1024)
+      return `${bytes} B`;
+    if (bytes < 1048576)
+      return `${(bytes / 1024).toFixed(2)} KB`;
+    if (bytes < 1073741824)
+      return `${(bytes / 1048576).toFixed(2)} MB`;
+    return `${(bytes / 1073741824).toFixed(2)} GB`;
+  }
+  isOneOf(mimeTypes) {
+    return mimeTypes.some((type) => {
+      if (type.endsWith("/*")) {
+        const category = type.slice(0, -2);
+        return this._file.type.startsWith(category);
+      }
+      return this._file.type === type;
+    });
+  }
+  isImage() {
+    return this._file.type.startsWith("image/");
+  }
+  isVideo() {
+    return this._file.type.startsWith("video/");
+  }
+  isAudio() {
+    return this._file.type.startsWith("audio/");
+  }
+  isPdf() {
+    return this._file.type === "application/pdf";
+  }
+}
+export function uploadedFile(file) {
+  return new UploadedFile(file);
+}
+export function uploadedFiles(files) {
+  return files.map((f) => new UploadedFile(f));
+}

package/dist/visibility.d.ts

@@ -0,0 +1,3 @@
+// type Visibility = 'public' | 'private'
+// export function setVisibility(path: string, visibility: Visibility) {
+export declare function setVisibility(): string;

package/dist/visibility.js

@@ -0,0 +1,3 @@
+export function setVisibility() {
+  return "wip";
+}

package/dist/zip.d.ts

@@ -0,0 +1,16 @@
+import type { ZlibCompressionOptions } from 'bun';
+import type { CommandError, Subprocess } from '@stacksjs/types';
+import type { Result } from '@stacksjs/error-handling';
+export declare function zip(from: string | string[], to?: string, options?: ZipOptions): Promise<Result<Subprocess, CommandError>>;
+export declare function unzip(paths: string | string[]): Promise<Result<Subprocess, CommandError>>;
+export declare function archive(paths: string | string[]): Promise<Result<Subprocess, CommandError>>;
+export declare function unarchive(paths: string | string[]): Promise<Result<Subprocess, CommandError>>;
+export declare function compress(paths: string[]): Promise<Result<Subprocess, CommandError>>;
+export declare function decompress(paths: string | string[]): Promise<Result<Subprocess, CommandError>>;
+export declare function gzipSync(data: Uint8Array, options?: ZlibCompressionOptions): Uint8Array;
+export declare function gunzipSync(data: Uint8Array): Uint8Array;
+export declare function deflateSync(data: Uint8Array, options?: ZlibCompressionOptions): Uint8Array;
+export declare function inflateSync(data: Uint8Array): Uint8Array;
+declare interface ZipOptions {
+  cwd?: string
+}

package/dist/zip.js

@@ -0,0 +1,41 @@
+import { runCommand } from "@stacksjs/cli";
+function shellEscape(_arg) {
+  return `'${_arg.replace(/'/g, "'\\''")}'`;
+}
+export async function zip(from, to, options) {
+  const toPath = to || "archive.zip";
+  if (Array.isArray(from)) {
+    const fromPath = from.map((f) => shellEscape(f)).join(" ");
+    return runCommand(`zip -r ${shellEscape(toPath)} ${fromPath}`, options);
+  }
+  return runCommand(`zip -r ${shellEscape(toPath)} ${shellEscape(from)}`, options);
+}
+export async function unzip(paths) {
+  if (Array.isArray(paths))
+    return runCommand(`unzip ${paths.map((p) => shellEscape(p)).join(" ")}`);
+  return runCommand(`unzip ${shellEscape(paths)}`);
+}
+export function archive(paths) {
+  return zip(paths);
+}
+export function unarchive(paths) {
+  return unzip(paths);
+}
+export function compress(paths) {
+  return zip(paths);
+}
+export function decompress(paths) {
+  return unzip(paths);
+}
+export function gzipSync(data, options) {
+  return Bun.gzipSync(data, options);
+}
+export function gunzipSync(data) {
+  return Bun.gunzipSync(data);
+}
+export function deflateSync(data, options) {
+  return Bun.deflateSync(data, options);
+}
+export function inflateSync(data) {
+  return Bun.inflateSync(data);
+}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/storage",
   "type": "module",
   "sideEffects": false,
-  "version": "0.70.88",
+  "version": "0.70.91",
   "description": "The Stacks file system.",
   "author": "Chris Breuer",
   "contributors": [
@@ -63,12 +63,12 @@
     }
   },
   "devDependencies": {
-    "@stacksjs/arrays": "0.70.88",
+    "@stacksjs/arrays": "0.70.91",
     "better-dx": "^0.2.16",
-    "@stacksjs/error-handling": "0.70.88",
-    "@stacksjs/path": "0.70.88",
-    "@stacksjs/strings": "0.70.88",
-    "@stacksjs/types": "0.70.88",
+    "@stacksjs/error-handling": "0.70.91",
+    "@stacksjs/path": "0.70.91",
+    "@stacksjs/strings": "0.70.91",
+    "@stacksjs/types": "0.70.91",
     "sharp": "^0.35.3"
   }
 }