[Sprint 16] Clear tsc + patch 0.1.1

jsr.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://jsr.io/schema/config-file.v1.json",
   "name": "@ninots/filesystem",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "exports": "./index.ts",
   "publish": {
     "include": [

package.json

@@ -3,7 +3,7 @@
   "main": "index.ts",
   "module": "index.ts",
   "type": "module",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "File system operations and storage abstraction for Bun",
   "author": "Ninots Framework",
   "keywords": [

src/adapters/local-adapter.ts

@@ -1,6 +1,6 @@
 import { appendFile, copyFile, mkdir, readdir, rename, rm, stat } from "node:fs/promises";
 import path from "node:path";
-import type { FilesystemDisk } from "../contracts/filesystem";
+import type { FileVisibility, FilesystemDisk } from "../contracts/filesystem";
 
 export interface LocalAdapterConfig {
     root: string;
@@ -59,6 +59,16 @@ export class LocalAdapter implements FilesystemDisk {
         return await file.exists();
     }
 
+    /**
+     * Determine if a file is missing.
+     *
+     * @param targetPath - The path to check
+     * @returns True if the file does not exist
+     */
+    async missing(targetPath: string): Promise<boolean> {
+        return !(await this.exists(targetPath));
+    }
+
     /**
      * Get the contents of a file.
      *
@@ -109,6 +119,22 @@ export class LocalAdapter implements FilesystemDisk {
         }
     }
 
+    /**
+     * Prepend data to a file.
+     *
+     * @param targetPath - The path to the file
+     * @param data - The data to prepend
+     * @returns True on success, false on failure
+     */
+    async prepend(targetPath: string, data: string): Promise<boolean> {
+        try {
+            const existing = (await this.get(targetPath)) ?? "";
+            return await this.put(targetPath, data + existing);
+        } catch {
+            return false;
+        }
+    }
+
     /**
      * Delete the file at a given path.
      *
@@ -201,15 +227,15 @@ export class LocalAdapter implements FilesystemDisk {
         }
     }
 
-    async getVisibility(targetPath: string): Promise<string | null> {
+    async getVisibility(targetPath: string): Promise<FileVisibility | null> {
         const file = Bun.file(this.applyPathPrefix(targetPath));
         if (!(await file.exists())) {
             return null;
         }
         return "private";
     }
 
-    async setVisibility(_targetPath: string, _visibility: string): Promise<boolean> {
+    async setVisibility(_targetPath: string, _visibility: FileVisibility): Promise<boolean> {
         // Local filesystem: visibility is a no-op (permissions may be managed externally)
         return true;
     }

src/adapters/s3-adapter.ts

@@ -1,5 +1,18 @@
 import type { FilesystemDisk } from "../contracts/filesystem";
 
+/**
+ * Bun S3 ACL values accepted by {@link Bun.S3Client} / presign.
+ */
+export type S3Acl =
+    | "private"
+    | "public-read"
+    | "public-read-write"
+    | "authenticated-read"
+    | "aws-exec-read"
+    | "bucket-owner-read"
+    | "bucket-owner-full-control"
+    | "log-delivery-write";
+
 /**
  * Configuration for S3Adapter.
  */
@@ -37,7 +50,7 @@ export interface S3AdapterConfig {
     /**
      * Default ACL for uploaded files (optional).
      */
-    acl?: "public-read" | "private" | "public-read-write" | "authenticated-read";
+    acl?: S3Acl;
 }
 
 /**
@@ -62,14 +75,20 @@ export interface S3AdapterConfig {
 export class S3Adapter implements FilesystemDisk {
     private client: import("bun").S3Client;
     private root: string;
-    private defaultAcl?: "public-read" | "private" | "public-read-write" | "authenticated-read";
+    private bucket: string;
+    private endpoint?: string;
+    private region: string;
+    private defaultAcl?: S3Acl;
 
     constructor(config: S3AdapterConfig) {
+        this.bucket = config.bucket;
+        this.endpoint = config.endpoint;
+        this.region = config.region ?? "us-east-1";
         this.client = new Bun.S3Client({
             accessKeyId: config.accessKeyId,
             bucket: config.bucket,
             endpoint: config.endpoint,
-            region: config.region,
+            region: this.region,
             secretAccessKey: config.secretAccessKey,
         });
         this.root = config.root ? this.normalizePath(config.root) : "";
@@ -445,8 +464,8 @@ export class S3Adapter implements FilesystemDisk {
     async url(path: string): Promise<string> {
         const key = this.resolvePath(path);
         // Return S3 URL format
-        const endpoint = this.client.endpoint || `https://s3.${this.client.region || "us-east-1"}.amazonaws.com`;
-        return `${endpoint}/${this.client.bucket}/${key}`;
+        const endpoint = this.endpoint || `https://s3.${this.region}.amazonaws.com`;
+        return `${endpoint}/${this.bucket}/${key}`;
     }
 
     /**
@@ -479,7 +498,7 @@ export class S3Adapter implements FilesystemDisk {
         options?: {
             contentType?: string;
             contentLength?: number;
-            acl?: string;
+            acl?: S3Acl;
         },
     ): Promise<{
         url: string;
@@ -491,7 +510,7 @@ export class S3Adapter implements FilesystemDisk {
 
         // Generate presigned URL for PUT upload
         const url = file.presign({
-            acl: options?.acl || this.defaultAcl || "public-read",
+            acl: options?.acl ?? this.defaultAcl ?? "public-read",
             expiresIn,
             method: "PUT",
             type: options?.contentType,
@@ -605,7 +624,7 @@ export class S3Adapter implements FilesystemDisk {
             const result = await this.client.list({ prefix });
             const results: string[] = [];
 
-            for (const obj of result.objects || []) {
+            for (const obj of result.contents ?? []) {
                 const key = obj.key;
                 if (!key) {
                     continue;
@@ -630,7 +649,7 @@ export class S3Adapter implements FilesystemDisk {
                     const parts = relativeKey.split("/");
                     if (parts.length > 1) {
                         const dirName = parts[0];
-                        if (!results.includes(dirName)) {
+                        if (dirName !== undefined && !results.includes(dirName)) {
                             results.push(dirName);
                         }
                     }

src/contracts/filesystem.ts

@@ -5,6 +5,11 @@
  * allowing application code to remain entirely agnostic to where files
  * are physically stored (local disk, cloud, etc.).
  */
+/**
+ * Laravel-style file visibility.
+ */
+export type FileVisibility = "public" | "private";
+
 export interface FilesystemDisk {
     /**
      * Determine if a file exists.
@@ -14,6 +19,14 @@ export interface FilesystemDisk {
      */
     exists(path: string): Promise<boolean>;
 
+    /**
+     * Determine if a file is missing (inverse of {@link exists}).
+     *
+     * @param path - The path to check
+     * @returns A promise resolving to true if it does not exist
+     */
+    missing(path: string): Promise<boolean>;
+
     /**
      * Get the contents of a file.
      *
@@ -130,15 +143,24 @@ export interface FilesystemDisk {
      */
     append(path: string, data: string): Promise<boolean>;
 
+    /**
+     * Prepend data to a file.
+     *
+     * @param path - The file path
+     * @param data - The data to prepend
+     * @returns A promise resolving to true on success
+     */
+    prepend(path: string, data: string): Promise<boolean>;
+
     /**
      * Get the visibility of a file (public/private).
      */
-    getVisibility(path: string): Promise<string | null>;
+    getVisibility(path: string): Promise<FileVisibility | null>;
 
     /**
      * Set the visibility of a file.
      */
-    setVisibility(path: string, visibility: string): Promise<boolean>;
+    setVisibility(path: string, visibility: FileVisibility): Promise<boolean>;
 
     /**
      * Get the MIME type of a file.

src/decorators/compressed-adapter.ts

@@ -1,5 +1,10 @@
 import type { FilesystemDisk } from "../contracts/filesystem";
 
+/**
+ * Bun gzip compression level (zlib / libdeflate).
+ */
+export type GzipLevel = -1 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+
 /**
  * Options for CompressedAdapter.
  */
@@ -17,10 +22,10 @@ export interface CompressedAdapterOptions {
     minSize?: number;
 
     /**
-     * Compression level (1-9).
+     * Compression level (1-9 zlib; up to 12 for libdeflate).
      * @default 6
      */
-    level?: number;
+    level?: GzipLevel;
 }
 
 /**
@@ -45,7 +50,7 @@ export class CompressedAdapter implements FilesystemDisk {
     private adapter: FilesystemDisk;
     private extensions?: string[];
     private minSize: number;
-    private level: number;
+    private level: GzipLevel;
 
     constructor(adapter: FilesystemDisk, options: CompressedAdapterOptions = {}) {
         this.adapter = adapter;
@@ -101,7 +106,7 @@ export class CompressedAdapter implements FilesystemDisk {
         const data = await this.adapter.get(compressedPath);
         if (data) {
             try {
-                const decompressed = await Bun.gunzip(data);
+                const decompressed = Bun.gunzipSync(data);
                 return new TextDecoder().decode(decompressed);
             } catch {
                 // If decompression fails, return as-is
@@ -134,7 +139,7 @@ export class CompressedAdapter implements FilesystemDisk {
                 }
 
                 // Compress and write
-                const compressed = await Bun.gzip(data, { level: this.level });
+                const compressed = Bun.gzipSync(new Uint8Array(data), { level: this.level });
                 return this.adapter.put(compressedPath, compressed);
             } catch (_error) {
                 return false;

src/decorators/scoped-adapter.ts

@@ -56,6 +56,9 @@ export class ScopedAdapter implements FilesystemDisk {
      * Write the contents of a file (scoped).
      */
     async put(path: string, contents: string | Blob | ArrayBuffer | Uint8Array): Promise<boolean> {
+        if (this.createScope) {
+            await this.adapter.makeDirectory(this.scope);
+        }
         return this.adapter.put(this.applyScope(path), contents);
     }
 

src/decorators/watched-adapter.ts

@@ -127,25 +127,31 @@ export class WatchedAdapter implements FilesystemDisk {
      */
     private createWatcher(path: string): void {
         try {
+            let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+
             const watcher = watch(path, { recursive: this.recursive }, (event, filename) => {
                 if (!filename) {
                     return;
                 }
 
-                // Debounce
                 const callbacks = this.callbacks.get(path);
                 if (!callbacks) {
                     return;
                 }
 
                 const eventType = event === "change" ? "change" : "rename";
 
-                // Call all callbacks
-                for (const callback of callbacks) {
-                    try {
-                        callback(eventType, filename);
-                    } catch (_error) {}
+                if (debounceTimer !== null) {
+                    clearTimeout(debounceTimer);
                 }
+
+                debounceTimer = setTimeout(() => {
+                    for (const callback of callbacks) {
+                        try {
+                            callback(eventType, filename);
+                        } catch (_error) {}
+                    }
+                }, this.debounce);
             });
 
             this.watchers.set(path, watcher);

src/manager.ts

@@ -1,5 +1,5 @@
 import { LocalAdapter } from "./adapters/local-adapter";
-import type { FilesystemDisk } from "./contracts/filesystem";
+import type { FileVisibility, FilesystemDisk } from "./contracts/filesystem";
 
 export interface FilesystemConfig {
     /**
@@ -93,6 +93,9 @@ export class FilesystemManager implements FilesystemDisk {
     async exists(path: string): Promise<boolean> {
         return this.disk().exists(path);
     }
+    async missing(path: string): Promise<boolean> {
+        return this.disk().missing(path);
+    }
     async get(path: string): Promise<string | null> {
         return this.disk().get(path);
     }
@@ -135,12 +138,15 @@ export class FilesystemManager implements FilesystemDisk {
     async append(path: string, data: string): Promise<boolean> {
         return this.disk().append(path, data);
     }
+    async prepend(path: string, data: string): Promise<boolean> {
+        return this.disk().prepend(path, data);
+    }
 
-    async getVisibility(path: string): Promise<string | null> {
+    async getVisibility(path: string): Promise<FileVisibility | null> {
         return this.disk().getVisibility(path);
     }
 
-    async setVisibility(path: string, visibility: string): Promise<boolean> {
+    async setVisibility(path: string, visibility: FileVisibility): Promise<boolean> {
         return this.disk().setVisibility(path, visibility);
     }
 

src/testing/helpers.ts

@@ -1,3 +1,4 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import crypto from "node:crypto";
 import { mkdir, rm } from "node:fs/promises";
 import path from "node:path";