@stacksjs/storage 0.70.88 → 0.70.91

package/dist/facade.js

@@ -0,0 +1,226 @@
+import { resolve } from "node:path";
+import process from "node:process";
+import { filesystems, app as appConfig } from "@stacksjs/config";
+import { createLocalStorage } from "./adapters/local";
+import { S3StorageAdapter } from "./adapters/s3";
+import { parseDiskPath } from "./path-sanitize";
+import { putUploadedFile } from "./put-file";
+function buildConfig() {
+  const cwd = process.cwd(), rootDir = filesystems.root || cwd, s3Config = filesystems.s3, appUrl = appConfig?.url || "", config = {
+    default: filesystems.driver || "local",
+    disks: {
+      local: {
+        driver: "local",
+        root: resolve(rootDir, "storage/app"),
+        visibility: filesystems.defaultVisibility || "private"
+      },
+      public: {
+        driver: "local",
+        root: resolve(rootDir, "public"),
+        url: appUrl ? `${appUrl}/storage` : "/storage",
+        visibility: "public"
+      }
+    }
+  };
+  if (s3Config?.bucket)
+    config.disks.s3 = {
+      driver: "s3",
+      bucket: s3Config.bucket,
+      region: s3Config.region || "us-east-1",
+      prefix: s3Config.prefix,
+      endpoint: s3Config.endpoint,
+      url: filesystems.publicUrl?.domain,
+      usePathStyleEndpoint: !!s3Config.endpoint,
+      visibility: filesystems.defaultVisibility || "private",
+      credentials: s3Config.credentials ? { key: s3Config.credentials.accessKeyId, secret: s3Config.credentials.secretAccessKey } : void 0
+    };
+  return config;
+}
+
+class StorageManager {
+  _config = null;
+  disks = new Map;
+  customConfig = null;
+  get config() {
+    if (!this._config) {
+      const builtConfig = buildConfig();
+      this._config = this.customConfig ? {
+        default: this.customConfig.default || builtConfig.default,
+        disks: { ...builtConfig.disks, ...this.customConfig.disks }
+      } : builtConfig;
+    }
+    return this._config;
+  }
+  init(config) {
+    this.customConfig = config;
+    this._config = null;
+    this.disks.clear();
+    return this;
+  }
+  disk(name) {
+    const diskName = name || this.config.default;
+    if (this.disks.has(diskName))
+      return this.disks.get(diskName);
+    const diskConfig = this.config.disks[diskName];
+    if (!diskConfig) {
+      const available = Object.keys(this.config.disks).join(", ");
+      throw Error(`Disk [${diskName}] is not configured. Available: ${available}`);
+    }
+    const adapter = this.createAdapter(diskName, diskConfig);
+    this.disks.set(diskName, adapter);
+    return adapter;
+  }
+  createAdapter(name, config) {
+    switch (config.driver) {
+      case "local":
+        return this.createLocalAdapter(config);
+      case "s3":
+        return this.createS3Adapter(name, config);
+      default:
+        throw Error(`Unsupported driver: ${config.driver}`);
+    }
+  }
+  createLocalAdapter(config) {
+    return createLocalStorage({ root: config.root });
+  }
+  createS3Adapter(_name, config) {
+    return new S3StorageAdapter(null, {
+      bucket: config.bucket,
+      region: config.region,
+      prefix: config.prefix
+    });
+  }
+  async put(pathOrFile, contentsOrOpts) {
+    if (typeof pathOrFile === "string")
+      return this.disk().write(pathOrFile, contentsOrOpts);
+    return putUploadedFile(this, pathOrFile, contentsOrOpts ?? {});
+  }
+  async stat(path) {
+    return this.disk().stat(path);
+  }
+  async getStream(path, options) {
+    const adapter = this.disk();
+    if (typeof adapter.getStream !== "function")
+      throw Error(`[storage] disk '${this.config.default}' does not support getStream \u2014 adapter is missing the optional method`);
+    return adapter.getStream(path, options);
+  }
+  async putStream(path, stream, options) {
+    const adapter = this.disk();
+    if (typeof adapter.putStream !== "function")
+      throw Error(`[storage] disk '${this.config.default}' does not support putStream \u2014 adapter is missing the optional method`);
+    return adapter.putStream(path, stream, options);
+  }
+  async copyAcross(source, dest) {
+    const src = parseDiskPath(source), dst = parseDiskPath(dest);
+    if (src.disk === dst.disk) {
+      const adapter = this.disk(src.disk);
+      await adapter.copyFile(src.path, dst.path);
+      return adapter.stat(dst.path).then((entry) => ({
+        path: dst.path,
+        size: entry.size,
+        contentType: entry.mimeType,
+        lastModified: entry.lastModified
+      }));
+    }
+    const contents = await this.disk(src.disk).read(src.path);
+    return this.disk(dst.disk).write(dst.path, contents);
+  }
+  async moveAcross(source, dest) {
+    const src = parseDiskPath(source), result = await this.copyAcross(source, dest);
+    await this.disk(src.disk).deleteFile(src.path);
+    return result;
+  }
+  async get(path) {
+    return this.disk().readToString(path);
+  }
+  async exists(path) {
+    return this.disk().fileExists(path);
+  }
+  async missing(path) {
+    return !await this.exists(path);
+  }
+  async delete(path) {
+    return this.disk().deleteFile(path);
+  }
+  async copy(from, to) {
+    return this.disk().copyFile(from, to);
+  }
+  async move(from, to) {
+    return this.disk().moveFile(from, to);
+  }
+  async url(path) {
+    return this.disk().publicUrl(path);
+  }
+  async signedUrl(path, options) {
+    const adapter = this.disk();
+    if (typeof adapter.signedUrl !== "function")
+      throw Error(`[storage] disk '${this.config.default}' does not support signedUrl`);
+    return adapter.signedUrl(path, options);
+  }
+  async presignedUploadUrl(options) {
+    const adapter = this.disk();
+    if (typeof adapter.presignedUploadUrl !== "function")
+      throw Error(`[storage] disk '${this.config.default}' does not support presignedUploadUrl \u2014 only S3-style adapters do. Use \`Storage.put(file, opts)\` for local/proxied uploads.`);
+    return adapter.presignedUploadUrl(options);
+  }
+  async presignedUploadPolicy(options) {
+    const adapter = this.disk();
+    if (typeof adapter.presignedUploadPolicy !== "function")
+      throw Error(`[storage] disk '${this.config.default}' does not support presignedUploadPolicy \u2014 S3-only. Use \`presignedUploadUrl\` for the PUT-form, or \`Storage.put(file, opts)\` for server-proxied uploads.`);
+    return adapter.presignedUploadPolicy(options);
+  }
+  async size(path) {
+    return this.disk().fileSize(path);
+  }
+  async lastModified(path) {
+    return this.disk().lastModified(path);
+  }
+  async mimeType(path) {
+    return this.disk().mimeType(path);
+  }
+  async checksum(path, algorithm) {
+    return this.disk().checksum(path, { algorithm });
+  }
+  async makeDirectory(path) {
+    return this.disk().createDirectory(path);
+  }
+  async deleteDirectory(path) {
+    return this.disk().deleteDirectory(path);
+  }
+  files(path = "") {
+    return this.disk().list(path);
+  }
+  allFiles(path = "") {
+    return this.disk().list(path, { deep: !0 });
+  }
+  configure(name, config) {
+    const currentConfig = this.config;
+    currentConfig.disks[name] = config;
+    this.disks.delete(name);
+    return this;
+  }
+  setDefaultDisk(name) {
+    if (!this.config.disks[name])
+      throw Error(`Disk [${name}] is not configured`);
+    this.config.default = name;
+    return this;
+  }
+  getDiskConfig(name) {
+    return this.config.disks[name || this.config.default];
+  }
+  getConfiguredDisks() {
+    return Object.keys(this.config.disks);
+  }
+  getDefaultDisk() {
+    return this.config.default;
+  }
+  reset() {
+    this._config = null;
+    this.customConfig = null;
+    this.disks.clear();
+    return this;
+  }
+}
+export const Storage = new StorageManager;
+
+export { StorageManager };

package/dist/files.d.ts

@@ -0,0 +1,52 @@
+import type { JsonFile, PackageJson, TextFile } from '@stacksjs/types';
+/**
+ * Reads a JSON file and returns the parsed data.
+ */
+export declare function readJsonFile(name: string, cwd?: string): Promise<JsonFile>;
+/**
+ * Reads a package.json file and returns the parsed data.
+ */
+export declare function readPackageJson(name: string, cwd?: string): Promise<PackageJson>;
+/**
+ * Writes the given text to the specified file.
+ */
+export declare function writeFile(path: string, data: any): Promise<number>;
+/**
+ * Writes the given data to the specified JSON file.
+ */
+export declare function writeJsonFile(file: JsonFile): Promise<number>;
+/**
+ * Reads a text file and returns its contents.
+ */
+export declare function readTextFile(name: string, cwd?: string): Promise<TextFile>;
+/**
+ * Writes the given text to the specified file.
+ */
+export declare function writeTextFile(file: TextFile): Promise<number>;
+export declare function doesExist(path: string): boolean;
+export declare function doesNotExist(path: string): boolean;
+/**
+ * Determine whether a folder has any files in it.
+ */
+export declare function hasFiles(folder: string): boolean;
+export declare function hasComponents(): boolean;
+export declare function hasFunctions(): boolean;
+export declare function deleteFiles(dir: string, exclude?: string[]): void;
+export declare function getFiles(dir: string, exclude?: string[]): string[];
+export declare function put(path: string, contents: string): void;
+export declare function get(path: string): Promise<string>;
+export declare const files: Files;
+export declare interface Files {
+  readJsonFile: typeof readJsonFile
+  readPackageJson: typeof readPackageJson
+  readTextFile: typeof readTextFile
+  writeJsonFile: typeof writeJsonFile
+  writeTextFile: typeof writeTextFile
+  hasFiles: typeof hasFiles
+  hasComponents: typeof hasComponents
+  hasFunctions: typeof hasFunctions
+  deleteFiles: typeof deleteFiles
+  getFiles: typeof getFiles
+  put: typeof put
+  get: typeof get
+}

package/dist/files.js

@@ -0,0 +1,126 @@
+import { contains } from "@stacksjs/arrays";
+import { log } from "@stacksjs/logging";
+import { dirname, join, path as p } from "@stacksjs/path";
+import { detectIndent, detectNewline } from "@stacksjs/strings";
+import { createFolder, isFolder } from "./folders";
+import { existsSync, fs } from "./fs";
+export async function readJsonFile(name, cwd) {
+  const file = await readTextFile(name, cwd);
+  let data;
+  try {
+    data = JSON.parse(file.data);
+  } catch (error) {
+    throw Error(`Failed to parse JSON file "${name}": ${error.message}`);
+  }
+  const indent = detectIndent(file.data).indent, newline = detectNewline(file.data);
+  return { ...file, data, indent, newline };
+}
+export async function readPackageJson(name, cwd) {
+  return (await readJsonFile(name, cwd)).data;
+}
+export async function writeFile(path, data) {
+  if (typeof path === "string") {
+    const dirPath = dirname(path);
+    if (!await existsSync(dirPath))
+      await createFolder(dirPath);
+    return await Bun.write(Bun.file(path), data);
+  }
+  return await Bun.write(path, data);
+}
+export async function writeJsonFile(file) {
+  let json = JSON.stringify(file.data, void 0, file.indent);
+  if (file.newline)
+    json += file.newline;
+  return writeTextFile({ ...file, data: json });
+}
+export function readTextFile(name, cwd) {
+  return new Promise((resolve, reject) => {
+    let filePath;
+    if (cwd)
+      filePath = join(cwd, name);
+    else
+      filePath = name;
+    fs.readFile(filePath, "utf8", (err, text) => {
+      if (err)
+        reject(err);
+      else
+        resolve({
+          path: filePath,
+          data: text
+        });
+    });
+  });
+}
+export async function writeTextFile(file) {
+  return await Bun.write(file.path, file.data);
+}
+function isFile(path) {
+  return fs.existsSync(path);
+}
+export function doesExist(path) {
+  return isFile(path) || isFolder(path);
+}
+export function doesNotExist(path) {
+  return !isFile(path) && !isFolder(path);
+}
+export function hasFiles(folder) {
+  try {
+    return fs.readdirSync(folder).length > 0;
+  } catch (err) {
+    log.debug(`Error reading folder: ${folder}`, err);
+    return !1;
+  }
+}
+export function hasComponents() {
+  return hasFiles(p.componentsPath());
+}
+export function hasFunctions() {
+  return hasFiles(p.functionsPath());
+}
+export function deleteFiles(dir, exclude = []) {
+  if (fs.existsSync(dir))
+    fs.readdirSync(dir).forEach((file) => {
+      const p = join(dir, file);
+      if (fs.statSync(p).isDirectory())
+        if (fs.readdirSync(p).length === 0)
+          fs.rmSync(p, { recursive: !0, force: !0 });
+        else
+          deleteFiles(p, exclude);
+      else if (!contains(p, exclude))
+        fs.rmSync(p);
+    });
+}
+export function getFiles(dir, exclude = []) {
+  let results = [];
+  fs.readdirSync(dir).forEach((file) => {
+    file = join(dir, file);
+    if (fs.statSync(file).isDirectory())
+      results = results.concat(getFiles(file, exclude));
+    else if (!contains(file, exclude))
+      results.push(file);
+  });
+  return results;
+}
+export function put(path, contents) {
+  const dirPath = dirname(path);
+  if (!fs.existsSync(dirPath))
+    fs.mkdirSync(dirPath, { recursive: !0 });
+  fs.writeFileSync(path, contents, "utf-8");
+}
+export async function get(path) {
+  return Bun.file(path).text();
+}
+export const files = {
+  readJsonFile,
+  readPackageJson,
+  readTextFile,
+  writeJsonFile,
+  writeTextFile,
+  hasFiles,
+  hasComponents,
+  hasFunctions,
+  deleteFiles,
+  getFiles,
+  put,
+  get
+};

package/dist/folders.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Determine whether a path is a folder.
+ */
+export declare function isFolder(path: string): boolean;
+// export function isDirectory(path: string): boolean {
+//   return isFolder(path)
+// }
+export declare function isDir(path: string): boolean;
+export declare function doesFolderExist(path: string): boolean;
+export declare function createFolder(dir: string): Promise<void>;
+export declare function getFolders(dir: string): string[];
+export declare const folders: Folders;
+export declare interface Folders {
+  isFolder: (path: string) => boolean
+  doesFolderExist: (path: string) => boolean
+  createFolder: (dir: string) => Promise<void>
+  getFolders: (dir: string) => string[]
+}

package/dist/folders.js

@@ -0,0 +1,36 @@
+import { join } from "@stacksjs/path";
+import { fs } from "./fs";
+export function isFolder(path) {
+  try {
+    return fs.statSync(path).isDirectory();
+  } catch {
+    return !1;
+  }
+}
+export function isDir(path) {
+  return isFolder(path);
+}
+export function doesFolderExist(path) {
+  return fs.existsSync(path);
+}
+export function createFolder(dir) {
+  return new Promise((resolve, reject) => {
+    try {
+      fs.mkdirSync(dir, { recursive: !0 });
+      resolve();
+    } catch (err) {
+      reject(err);
+    }
+  });
+}
+export function getFolders(dir) {
+  return fs.readdirSync(dir).filter((file) => {
+    return fs.statSync(join(dir, file)).isDirectory();
+  });
+}
+export const folders = {
+  isFolder,
+  doesFolderExist,
+  createFolder,
+  getFolders
+};

package/dist/fs.d.ts

@@ -0,0 +1,4 @@
+import { existsSync, watch as fsWatch, mkdirSync, readFileSync, watchFile, writeFileSync } from 'node:fs';
+import * as fs from 'node:fs';
+export declare function exists(path: string): boolean;
+export { existsSync, fsWatch, mkdirSync, readFileSync, watchFile, writeFileSync, fs };

package/dist/fs.js

@@ -0,0 +1,7 @@
+import * as fs from "node:fs";
+import { existsSync, watch as fsWatch, mkdirSync, readFileSync, watchFile, writeFileSync } from "node:fs";
+export function exists(path) {
+  return existsSync(path);
+}
+
+export { existsSync, fsWatch, mkdirSync, readFileSync, watchFile, writeFileSync, fs };

package/dist/glob.d.ts

@@ -0,0 +1,13 @@
+export declare function globSync(patterns: string | string[], options?: Omit<GlobOptions, 'patterns'>): string[];
+export declare function glob(patterns: string | string[], options?: Omit<GlobOptions, 'patterns'>): Promise<string[]>;
+export declare interface GlobOptions {
+  absolute?: boolean
+  cwd?: string
+  patterns?: string[]
+  ignore?: string[]
+  dot?: boolean
+  deep?: number
+  expandDirectories?: boolean
+  onlyDirectories?: boolean
+  onlyFiles?: boolean
+}

package/dist/glob.js

@@ -0,0 +1,40 @@
+import { Glob as BunGlob } from "bun";
+function isEnoent(err) {
+  return !!err && typeof err === "object" && err.code === "ENOENT";
+}
+export function globSync(patterns, options) {
+  const patternArray = typeof patterns === "string" ? [patterns] : patterns, results = [];
+  for (const pattern of patternArray)
+    try {
+      const matches = new BunGlob(pattern).scanSync({
+        cwd: options?.cwd,
+        absolute: options?.absolute,
+        dot: options?.dot,
+        onlyFiles: options?.onlyFiles
+      });
+      for (const match of matches)
+        results.push(match);
+    } catch (err) {
+      if (!isEnoent(err))
+        throw err;
+    }
+  return results;
+}
+export async function glob(patterns, options) {
+  const patternArray = typeof patterns === "string" ? [patterns] : patterns, results = [];
+  for (const pattern of patternArray)
+    try {
+      const matches = new BunGlob(pattern).scan({
+        cwd: options?.cwd,
+        absolute: options?.absolute,
+        dot: options?.dot,
+        onlyFiles: options?.onlyFiles
+      });
+      for await (const match of matches)
+        results.push(match);
+    } catch (err) {
+      if (!isEnoent(err))
+        throw err;
+    }
+  return results;
+}

package/dist/hash.d.ts

@@ -0,0 +1,5 @@
+import type { Hash } from 'node:crypto';
+export declare function hashFileOrDirectory(path: string, hash: Hash): void;
+export declare function hashDirectory(directory: string): string;
+export declare function hashPath(path: string): string;
+export declare function hashPaths(paths: string | string[]): string;

package/dist/hash.js

@@ -0,0 +1,33 @@
+import { createHash } from "node:crypto";
+import { path as p } from "@stacksjs/path";
+import { fs } from "./fs";
+export function hashFileOrDirectory(path, hash) {
+  if (!fs.existsSync(path)) {
+    console.error(`Path does not exist: ${path}`);
+    return;
+  }
+  if (fs.statSync(path).isDirectory()) {
+    const files = fs.readdirSync(path);
+    for (const file of files) {
+      const filePath = p.join(path, file);
+      hashFileOrDirectory(filePath, hash);
+    }
+  } else
+    hash.update(fs.readFileSync(path));
+}
+export function hashDirectory(directory) {
+  const hash = createHash("sha256");
+  hashFileOrDirectory(directory, hash);
+  return hash.digest("hex");
+}
+export function hashPath(path) {
+  const hash = createHash("sha256");
+  hashFileOrDirectory(path, hash);
+  return hash.digest("hex");
+}
+export function hashPaths(paths) {
+  const hash = createHash("sha256"), pathsArray = Array.isArray(paths) ? paths : [paths];
+  for (const path of pathsArray)
+    hashFileOrDirectory(path, hash);
+  return hash.digest("hex");
+}

package/dist/helpers.d.ts

@@ -0,0 +1,7 @@
+export declare function updateConfigFile(filePath: string, newConfig: Record<string, unknown>): Promise<void>;
+export declare const _dirname: string;
+export declare const helpers: Helpers;
+declare interface Helpers {
+  _dirname: string
+  updateConfigFile: (filePath: string, newConfig: Record<string, unknown>) => Promise<void>
+}

package/dist/helpers.js

@@ -0,0 +1,28 @@
+var __dirname = "";
+import { fileURLToPath } from "node:url";
+import { dirname } from "@stacksjs/path";
+import { fs } from "./fs";
+export const _dirname = typeof __dirname < "u" ? __dirname : dirname(fileURLToPath(import.meta.url));
+export function updateConfigFile(filePath, newConfig) {
+  return new Promise((resolve, reject) => {
+    let config;
+    try {
+      config = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    } catch (error) {
+      reject(Error(`Failed to parse config file "${filePath}": ${error.message}`));
+      return;
+    }
+    for (const key in newConfig)
+      config[key] = newConfig[key];
+    try {
+      fs.writeFileSync(filePath, JSON.stringify(config, null, 2));
+      resolve();
+    } catch (error) {
+      reject(error);
+    }
+  });
+}
+export const helpers = {
+  _dirname,
+  updateConfigFile
+};

package/dist/image.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Wrap a Sharp pipeline so it composes with
+ * `Storage.put(file, { transform })`. The pipeline function receives a
+ * fresh Sharp instance preloaded with the file's bytes; its return
+ * value is the final pipeline chain (sharp's methods are chainable so
+ * "return img.resize(...)" is the normal shape).
+ *
+ * The wrapper handles the buffer normalisation + final `.toBuffer()`
+ * call so callers don't have to.
+ */
+export declare function transform(pipeline: (img: SharpInstance) => SharpInstance | Promise<SharpInstance>): (input: Uint8Array | Buffer | ArrayBuffer) => Promise<Buffer>;
+/**
+ * Common preset for square avatars — resizes + crops to fit, encodes
+ * as WebP at quality 85. Covers the by-far most common
+ * `Storage.put(file, { transform: ... })` callsite.
+ *
+ * @example
+ * ```ts
+ * import { avatar } from '@stacksjs/storage/image'
+ *
+ * await Storage.put(file, {
+ *   dir: 'avatars',
+ *   transform: avatar(512),
+ * })
+ * ```
+ */
+export declare function avatar(size?: number, quality?: number): (input: Uint8Array | Buffer | ArrayBuffer) => Promise<Buffer>;
+/**
+ * Generic resize preset. `fit` defaults to `'inside'` (preserve aspect
+ * ratio, don't crop) which is the most common non-avatar case.
+ */
+export declare function resize(width: number, height: number, fit?: 'cover' | 'contain' | 'fill' | 'inside' | 'outside'): (input: Uint8Array | Buffer | ArrayBuffer) => Promise<Buffer>;
+/**
+ * Strip EXIF + colour profile + other embedded metadata. Useful when
+ * accepting user uploads where you don't want to leak GPS coordinates
+ * embedded in phone photos. Pairs well with resize/format presets via
+ * the explicit `transform()` form when needed.
+ *
+ * sharp strips metadata by default unless `withMetadata()` is called;
+ * this preset just makes the intent explicit.
+ */
+export declare function stripMetadata(): (input: Uint8Array | Buffer | ArrayBuffer) => Promise<Buffer>;
+declare interface SharpInstance {
+  toBuffer(): Promise<Buffer>
+  resize: (...args: unknown[]) => SharpInstance
+  jpeg: (...args: unknown[]) => SharpInstance
+  png: (...args: unknown[]) => SharpInstance
+  webp: (...args: unknown[]) => SharpInstance
+  avif: (...args: unknown[]) => SharpInstance
+  gif: (...args: unknown[]) => SharpInstance
+  rotate: (...args: unknown[]) => SharpInstance
+  blur: (...args: unknown[]) => SharpInstance
+  withMetadata: (...args: unknown[]) => SharpInstance
+  [k: string]: unknown
+}