v4.5.1

fix(readme): refresh documentation wording and simplify README formatting
v4.5.0
2026-03-14 22:42:29 +00:00 · 2026-03-14 22:42:29 +00:00 · 2026-03-14 19:24:36 +00:00 · 2026-03-14 19:24:36 +00:00 · 2026-01-25 18:10:51 +00:00 · 2026-01-25 18:09:38 +00:00
25 changed files with 13508 additions and 4065 deletions
--- a/changelog.md
+++ b/changelog.md
@@ -1,5 +1,120 @@
 # Changelog
 ## 2026-03-14 - 4.5.1 - fix(readme)
 refresh documentation wording and simplify README formatting
 - removes emoji-heavy headings and inline log examples for a cleaner presentation
 - clarifies S3-compatible storage wording in the project description
 - streamlines testing and error handling sections without changing library functionality
 ## 2026-03-14 - 4.5.0 - feat(storage)
 generalize S3 client and watcher interfaces to storage-oriented naming with backward compatibility
 - rename SmartBucket internals from s3Client to storageClient and normalize configuration using storage descriptor types
 - update watcher and interface types from S3-specific names to storage-oriented equivalents while keeping deprecated aliases
 - refresh tests and documentation comments to reflect S3-compatible object storage terminology
 - bump build, test, AWS SDK, and related dependency versions
 ## 2026-01-25 - 4.4.1 - fix(tests)
 add explicit 'as string' type assertions to environment variable retrievals in tests
 - Add 'as string' assertions for S3_ACCESSKEY, S3_SECRETKEY, S3_ENDPOINT, and S3_BUCKET to satisfy TypeScript typings in tests
 - Cast S3_PORT to string before parseInt to ensure correct input type and avoid compiler errors
 - Changes are localized to test/test.listing.node+deno.ts
 ## 2026-01-25 - 4.4.0 - feat(watcher)
 add polling-based BucketWatcher to detect add/modify/delete events and expose RxJS Observable and EventEmitter APIs
 - Add new BucketWatcher implementation (ts/classes.watcher.ts) with polling, buffering and change detection by ETag/Size/LastModified
 - Expose createWatcher(...) on Bucket (ts/classes.bucket.ts) and export watcher and interfaces from index (ts/index.ts)
 - Add watcher-related interfaces (IS3ChangeEvent, IS3ObjectState, IBucketWatcherOptions) to ts/interfaces.ts
 - Comprehensive README/docs additions and examples for BucketWatcher, buffering, options and use cases (readme.md, readme.hints.md)
 - Add unit/integration tests for watcher behavior (test/test.watcher.node.ts)
 - Non-breaking API additions only — ready for a minor version bump from 4.3.1 to 4.4.0
 ## 2026-01-24 - 4.3.1 - fix(bucket)
 propagate S3 client errors instead of silently logging them; update build script, bump dev/dependencies, and refresh npmextra configuration
 - Remove .catch(...) wrappers around s3Client.send so errors are no longer swallowed and will propagate to callers
 - Update build script to use 'tsbuild tsfolders --allowimplicitany'
 - Bump devDependencies: @git.zone/tsbuild to ^4.1.2, @git.zone/tsrun to ^2.0.1, @git.zone/tstest to ^3.1.6
 - Bump dependency @aws-sdk/client-s3 to ^3.975.0
 - Adjust npmextra.json structure (@git.zone/cli, @git.zone/tsdoc), add release registries and @ship.zone/szci entry
 - Remove pnpm-workspace.yaml onlyBuiltDependencies configuration
 ## 2025-11-20 - 4.3.0 - feat(listing)
 Add memory-efficient listing APIs: async generator, RxJS observable, and cursor pagination; export ListCursor and Minimatch; add minimatch dependency; bump to 4.2.0
 - Added memory-efficient listing methods on Bucket: listAllObjects (async generator), listAllObjectsObservable (RxJS Observable), createCursor (returns ListCursor) and listAllObjectsArray (convenience array collector).
 - New ListCursor class (ts/classes.listcursor.ts) providing page-based iteration: next(), hasMore(), reset(), getToken()/setToken().
 - Added glob matching helper findByGlob(pattern) using minimatch (exported via plugins.Minimatch).
 - Exported ListCursor from ts/index.ts and exported Minimatch via ts/plugins.ts.
 - Added minimatch dependency in package.json and bumped package version to 4.2.0; increased test timeout to 120s.
 - Updated tests to read S3_SECRETKEY, S3_PORT and to assert bucket name from env (test/test.node+deno.ts, test/test.trash.node+deno.ts).
 - No breaking changes: new APIs are additive and existing behavior preserved.
 ## 2025-11-20 - 4.2.0 - feat(listing)
 Add memory-efficient listing with async generators, RxJS observables, and cursor pagination for huge buckets
 **New Memory-Efficient Listing Methods:**
 **Async Generator (Recommended for most use cases):**
 - `Bucket.listAllObjects(prefix?)` - Stream object keys one at a time using `for await...of`
 - `Bucket.findByGlob(pattern)` - Find objects matching glob patterns (e.g., `**/*.json`, `npm/packages/*/index.json`)
 - Memory efficient, supports early termination, composable
 **RxJS Observable (For complex reactive pipelines):**
 - `Bucket.listAllObjectsObservable(prefix?)` - Emit keys as Observable for use with RxJS operators (filter, map, take, etc.)
 - Perfect for complex data transformations and reactive architectures
 **Cursor Pattern (For manual pagination control):**
 - `Bucket.createCursor(prefix?, options?)` - Create cursor for explicit page-by-page iteration
 - `ListCursor.next()` - Fetch next page of results
 - `ListCursor.hasMore()` - Check if more results available
 - `ListCursor.reset()` - Reset to beginning
 - `ListCursor.getToken()` / `ListCursor.setToken()` - Save/restore pagination state
 - Ideal for UI pagination and resumable operations
 **Convenience Methods:**
 - `Bucket.listAllObjectsArray(prefix?)` - Collect all keys into array (WARNING: loads all into memory)
 **Benefits:**
 - ✅ Memory-efficient streaming for buckets with millions of objects
 - ✅ Three patterns for different use cases (generators, observables, cursors)
 - ✅ Support for early termination and incremental processing
 - ✅ Glob pattern matching with minimatch
 - ✅ Full TypeScript support with proper types
 - ✅ Zero breaking changes - all new methods
 **Dependencies:**
 - Added `minimatch` for glob pattern support
 **Files Changed:**
 - `ts/classes.bucket.ts` - Added all listing methods
 - `ts/classes.listcursor.ts` - NEW: Cursor implementation
 - `ts/plugins.ts` - Export Minimatch
 - `ts/index.ts` - Export ListCursor
 - `test/test.listing.node+deno.ts` - NEW: Comprehensive listing tests
 - `package.json` - Added minimatch dependency
 ## 2025-11-20 - 4.1.0 - feat(core)
 Add S3 endpoint normalization, directory pagination, improved metadata checks, trash support, and related tests
 - Add normalizeS3Descriptor helper to sanitize and normalize various S3 endpoint formats and emit warnings for mismatches (helpers.ts).
 - Use normalized endpoint and credentials when constructing S3 client in SmartBucket (classes.smartbucket.ts).
 - Implement paginated listing helper listObjectsV2AllPages in Directory and use it for listFiles and listDirectories to aggregate Contents and CommonPrefixes across pages (classes.directory.ts).
 - Improve MetaData.hasMetaData to catch NotFound errors and return false instead of throwing (classes.metadata.ts).
 - Export metadata and trash modules from index (ts/index.ts) and add a Trash class with utilities for trashed files and key encoding (classes.trash.ts).
 - Enhance Bucket operations: fastCopy now preserves or replaces native metadata correctly, cleanAllContents supports paginated deletion, and improved fastExists error handling (classes.bucket.ts).
 - Fix Directory.getSubDirectoryByName to construct new Directory instances with the correct parent directory reference.
 - Add tests covering metadata absence and pagination behavior (test/test.local.node+deno.ts).
 ## 2025-11-20 - 4.0.1 - fix(plugins)
 Use explicit node: imports for native path and stream modules in ts/plugins.ts
 - Replaced imports of 'path' and 'stream' with 'node:path' and 'node:stream' in ts/plugins.ts.
 - Ensures correct ESM resolution of Node built-ins when package.json type is 'module' and avoids accidental conflicts with userland packages.
 ## 2025-11-20 - 4.0.0 - BREAKING CHANGE(core)
 Make API strict-by-default: remove *Strict variants, throw on not-found/exists conflicts, add explicit exists() methods, update docs/tests and bump deps
--- a/deno.lock
+++ b/deno.lock
--- a/npmextra.json
+++ b/npmextra.json
@@ -1,8 +1,5 @@
 {
-  "npmci": {
+  "@git.zone/cli": {
    "npmGlobalTools": []
  },
  "gitzone": {
    "projectType": "npm",
    "module": {
      "githost": "code.foss.global",
@@ -33,9 +30,19 @@
        "data management",
        "streaming"
      ]
    },
    "release": {
      "registries": [
        "https://verdaccio.lossless.digital",
        "https://registry.npmjs.org"
      ],
      "accessLevel": "public"
    }
  },
-  "tsdoc": {
+  "@git.zone/tsdoc": {
    "legal": "\n## License and Legal Information\n\nThis repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. \n\n**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.\n\n### Trademarks\n\nThis project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.\n\n### Company Information\n\nTask Venture Capital GmbH  \nRegistered at District court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or if you require further information, please contact us via email at hello@task.vc.\n\nBy using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.\n"
  },
  "@ship.zone/szci": {
    "npmGlobalTools": []
  }
 }
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
  "name": "@push.rocks/smartbucket",
-  "version": "4.0.0",
+  "version": "4.5.1",
  "description": "A TypeScript library providing a cloud-agnostic interface for managing object storage with functionalities like bucket management, file and directory operations, and advanced features such as metadata handling and file locking.",
  "main": "dist_ts/index.js",
  "typings": "dist_ts/index.d.ts",
@@ -8,26 +8,28 @@
  "author": "Task Venture Capital GmbH",
  "license": "MIT",
  "scripts": {
-    "test": "(tstest test/ --verbose --logfile --timeout 60)",
+    "test": "(tstest test/ --verbose --logfile --timeout 120)",
-    "build": "(tsbuild --web --allowimplicitany)"
+    "build": "(tsbuild tsfolders --allowimplicitany)"
  },
  "devDependencies": {
-    "@git.zone/tsbuild": "^3.1.0",
+    "@git.zone/tsbuild": "^4.3.0",
-    "@git.zone/tsrun": "^2.0.0",
+    "@git.zone/tsrun": "^2.0.1",
-    "@git.zone/tstest": "^3.0.1",
+    "@git.zone/tstest": "^3.3.2",
    "@push.rocks/qenv": "^6.1.3",
-    "@push.rocks/tapbundle": "^6.0.3"
+    "@push.rocks/tapbundle": "^6.0.3",
    "@types/node": "^22.15.29"
  },
  "dependencies": {
-    "@aws-sdk/client-s3": "^3.936.0",
+    "@aws-sdk/client-s3": "^3.1009.0",
    "@push.rocks/smartmime": "^2.0.4",
    "@push.rocks/smartpath": "^6.0.0",
    "@push.rocks/smartpromise": "^4.2.3",
    "@push.rocks/smartrx": "^3.0.10",
-    "@push.rocks/smartstream": "^3.2.5",
+    "@push.rocks/smartstream": "^3.4.0",
    "@push.rocks/smartstring": "^4.1.0",
    "@push.rocks/smartunique": "^3.0.9",
-    "@tsclass/tsclass": "^9.3.0"
+    "@tsclass/tsclass": "^9.4.0",
    "minimatch": "^10.2.4"
  },
  "private": false,
  "files": [
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -1,4 +0,0 @@
 onlyBuiltDependencies:
  - esbuild
  - mongodb-memory-server
  - puppeteer
--- a/readme.hints.md
+++ b/readme.hints.md
@@ -3,3 +3,4 @@
 * **Use exists() methods to check before getting**: `bucketExists`, `fileExists`, `directoryExists`, `fastExists`
 * **No *Strict methods**: All removed (fastPutStrict, getBucketByNameStrict, getFileStrict, getSubDirectoryByNameStrict)
 * metadata is handled though the MetaData class. Important!
 * **BucketWatcher** - Polling-based S3 change watcher (`bucket.createWatcher()`). Detects add/modify/delete via ETag/Size/LastModified comparison. Supports RxJS Observable pattern (`changeSubject`) and EventEmitter pattern (`on('change')`). Options: `prefix`, `pollIntervalMs`, `bufferTimeMs`, `includeInitial`, `pageSize`.
--- a/readme.md
+++ b/readme.md
@@ -1,41 +1,92 @@
-# @push.rocks/smartbucket 🪣
+# @push.rocks/smartbucket
-> A powerful, cloud-agnostic TypeScript library for object storage with advanced features like file locking, metadata management, and intelligent trash handling.
+A powerful, cloud-agnostic TypeScript library for object storage that makes S3-compatible storage feel like a modern filesystem. Built for developers who demand simplicity, type-safety, and advanced features like real-time bucket watching, metadata management, file locking, intelligent trash handling, and memory-efficient streaming.
-## Install 📦
+## Issue Reporting and Security
-To install `@push.rocks/smartbucket`, run:
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
 ## Why SmartBucket?
 - **Cloud Agnostic** - Write once, run on AWS S3, MinIO, DigitalOcean Spaces, Backblaze B2, Wasabi, Cloudflare R2, or any S3-compatible storage
 - **Modern TypeScript** - First-class TypeScript support with complete type definitions and async/await patterns
 - **Real-Time Watching** - Monitor bucket changes with polling-based watcher supporting RxJS and EventEmitter patterns
 - **Memory Efficient** - Handle millions of files with async generators, RxJS observables, and cursor pagination
 - **Smart Trash System** - Recover accidentally deleted files with built-in trash and restore functionality
 - **File Locking** - Prevent concurrent modifications with built-in locking mechanisms
 - **Rich Metadata** - Attach custom metadata to any file for powerful organization and search
 - **Streaming Support** - Efficient handling of large files with Node.js and Web streams
 - **Directory-like API** - Intuitive filesystem-like operations on object storage
 - **Fail-Fast** - Strict-by-default API catches errors immediately with precise stack traces
 ## Quick Start
 ```typescript
 import { SmartBucket } from '@push.rocks/smartbucket';
 // Connect to your storage
 const storage = new SmartBucket({
  accessKey: 'your-access-key',
  accessSecret: 'your-secret-key',
  endpoint: 's3.amazonaws.com',
  port: 443,
  useSsl: true
 });
 // Get or create a bucket
 const bucket = await storage.getBucketByName('my-app-data');
 // Upload a file
 await bucket.fastPut({
  path: 'users/profile.json',
  contents: JSON.stringify({ name: 'Alice', role: 'admin' })
 });
 // Download it back
 const data = await bucket.fastGet({ path: 'users/profile.json' });
 console.log(JSON.parse(data.toString()));
 // List files efficiently (even with millions of objects!)
 for await (const key of bucket.listAllObjects('users/')) {
  console.log('Found:', key);
 }
 // Watch for changes in real-time
 const watcher = bucket.createWatcher({ prefix: 'uploads/', pollIntervalMs: 3000 });
 watcher.changeSubject.subscribe((change) => {
  console.log('Change detected:', change.type, change.key);
 });
 await watcher.start();
 ```
 ## Install
 ```bash
 # Using pnpm (recommended)
 pnpm add @push.rocks/smartbucket
 # Using npm
 npm install @push.rocks/smartbucket --save
 ```
-Or if you're using pnpm (recommended):
+## Usage
 ```bash
 pnpm add @push.rocks/smartbucket
 ```
 ## Usage 🚀
 ### Introduction
 `@push.rocks/smartbucket` provides a unified, cloud-agnostic API for object storage operations across major providers like AWS S3, Google Cloud Storage, MinIO, and more. It abstracts away provider-specific complexities while offering advanced features like metadata management, file locking, streaming operations, and intelligent trash management.
 ### Table of Contents
-1. [🏁 Getting Started](#-getting-started)
+1. [Getting Started](#getting-started)
-2. [🗂️ Working with Buckets](#️-working-with-buckets)
+2. [Working with Buckets](#working-with-buckets)
-3. [📁 File Operations](#-file-operations)
+3. [File Operations](#file-operations)
-4. [📂 Directory Management](#-directory-management)
+4. [Memory-Efficient Listing](#memory-efficient-listing)
-5. [🌊 Streaming Operations](#-streaming-operations)
+5. [Bucket Watching](#bucket-watching)
-6. [🔒 File Locking](#-file-locking)
+6. [Directory Management](#directory-management)
-7. [🏷️ Metadata Management](#️-metadata-management)
+7. [Streaming Operations](#streaming-operations)
-8. [🗑️ Trash & Recovery](#️-trash--recovery)
+8. [File Locking](#file-locking)
-9. [⚡ Advanced Features](#-advanced-features)
+9. [Metadata Management](#metadata-management)
-10. [☁️ Cloud Provider Support](#️-cloud-provider-support)
+10. [Trash & Recovery](#trash--recovery)
 11. [Advanced Features](#advanced-features)
 12. [Cloud Provider Support](#cloud-provider-support)
-### 🏁 Getting Started
+### Getting Started
 First, set up your storage connection:
@@ -53,24 +104,36 @@ const smartBucket = new SmartBucket({
 });
 ```
-### 🗂️ Working with Buckets
+**For MinIO or self-hosted storage:**
 ```typescript
 const smartBucket = new SmartBucket({
  accessKey: 'minioadmin',
  accessSecret: 'minioadmin',
  endpoint: 'localhost',
  port: 9000,
  useSsl: false // MinIO often runs without SSL locally
 });
 ```
 ### Working with Buckets
 #### Creating Buckets
 ```typescript
 // Create a new bucket
 const myBucket = await smartBucket.createBucket('my-awesome-bucket');
 console.log(`✅ Bucket created: ${myBucket.name}`);
 ```
 #### Getting Existing Buckets
 ```typescript
-// Get a bucket reference
+// Get a bucket reference (throws if not found - strict by default!)
 const existingBucket = await smartBucket.getBucketByName('existing-bucket');
-// Or use strict mode (throws if bucket doesn't exist)
+// Check first, then get (non-throwing approach)
-const bucketStrict = await smartBucket.getBucketByNameStrict('must-exist-bucket');
+if (await smartBucket.bucketExists('maybe-exists')) {
  const bucket = await smartBucket.getBucketByName('maybe-exists');
 }
 ```
 #### Removing Buckets
@@ -78,10 +141,9 @@ const bucketStrict = await smartBucket.getBucketByNameStrict('must-exist-bucket'
 ```typescript
 // Delete a bucket (must be empty)
 await smartBucket.removeBucket('old-bucket');
 console.log('🗑️ Bucket removed');
 ```
-### 📁 File Operations
+### File Operations
 #### Upload Files
@@ -115,7 +177,6 @@ try {
  });
 } catch (error) {
  console.error('Upload failed:', error.message);
  // Error: Object already exists at path 'existing-file.txt' in bucket 'my-bucket'. Set overwrite:true to replace it.
 }
 ```
@@ -126,10 +187,12 @@ try {
 const fileContent = await bucket.fastGet({
  path: 'documents/report.pdf'
 });
 console.log(`📄 File size: ${fileContent.length} bytes`);
 // Get file as string
 const textContent = fileContent.toString('utf-8');
 // Parse JSON files directly
 const jsonData = JSON.parse(fileContent.toString());
 ```
 #### Check File Existence
@@ -138,7 +201,6 @@ const textContent = fileContent.toString('utf-8');
 const exists = await bucket.fastExists({
  path: 'documents/report.pdf'
 });
 console.log(`File exists: ${exists ? '✅' : '❌'}`);
 ```
 #### Delete Files
@@ -164,9 +226,243 @@ await bucket.fastMove({
  sourcePath: 'temp/draft.txt',
  destinationPath: 'final/document.txt'
 });
 // Copy to different bucket
 const targetBucket = await smartBucket.getBucketByName('backup-bucket');
 await bucket.fastCopy({
  sourcePath: 'important/data.json',
  destinationPath: 'archived/data.json',
  targetBucket: targetBucket
 });
 ```
-### 📂 Directory Management
+### Memory-Efficient Listing
 SmartBucket provides three powerful patterns for listing objects, optimized for handling **millions of files** efficiently:
 #### Async Generators (Recommended)
 Memory-efficient streaming using native JavaScript async iteration:
 ```typescript
 // List all objects with prefix - streams one at a time!
 for await (const key of bucket.listAllObjects('documents/')) {
  console.log('Found:', key);
  // Process each file individually (memory efficient!)
  const content = await bucket.fastGet({ path: key });
  processFile(content);
  // Early termination support
  if (shouldStop()) break;
 }
 // Find objects matching glob patterns
 for await (const key of bucket.findByGlob('**/*.json')) {
  console.log('JSON file:', key);
 }
 // Complex glob patterns
 for await (const key of bucket.findByGlob('npm/packages/*/index.json')) {
  console.log('Package index:', key);
 }
 for await (const key of bucket.findByGlob('images/*.{jpg,png,gif}')) {
  console.log('Image:', key);
 }
 ```
 **Why use async generators?**
 - Processes one item at a time (constant memory usage)
 - Supports early termination with `break`
 - Native JavaScript - no dependencies
 - Perfect for large buckets with millions of objects
 #### RxJS Observables
 Perfect for reactive pipelines and complex data transformations:
 ```typescript
 import { filter, take, map } from 'rxjs/operators';
 // Stream keys as Observable with powerful operators
 bucket.listAllObjectsObservable('logs/')
  .pipe(
    filter(key => key.endsWith('.log')),
    take(100),
    map(key => ({ key, timestamp: Date.now() }))
  )
  .subscribe({
    next: (item) => console.log('Log file:', item.key),
    error: (err) => console.error('Error:', err),
    complete: () => console.log('Listing complete')
  });
 // Combine with other observables
 import { merge } from 'rxjs';
 const logs$ = bucket.listAllObjectsObservable('logs/');
 const backups$ = bucket.listAllObjectsObservable('backups/');
 merge(logs$, backups$)
  .pipe(filter(key => key.includes('2024')))
  .subscribe(key => console.log('2024 file:', key));
 ```
 #### Cursor Pattern
 Explicit pagination control for UI and resumable operations:
 ```typescript
 // Create cursor with custom page size
 const cursor = bucket.createCursor('uploads/', { pageSize: 100 });
 // Fetch pages manually
 while (cursor.hasMore()) {
  const page = await cursor.next();
  console.log(`Page has ${page.keys.length} items`);
  for (const key of page.keys) {
    console.log(`  - ${key}`);
  }
  if (page.done) break;
 }
 // Save and restore cursor state (perfect for resumable operations!)
 const token = cursor.getToken();
 // Store token in database or session...
 // ... later, in a different request ...
 const newCursor = bucket.createCursor('uploads/', { pageSize: 100 });
 newCursor.setToken(token); // Resume from saved position!
 const nextPage = await newCursor.next();
 // Reset cursor to start over
 cursor.reset();
 ```
 #### Convenience Methods
 ```typescript
 // Collect all keys into array (WARNING: loads everything into memory!)
 const allKeys = await bucket.listAllObjectsArray('images/');
 console.log(`Found ${allKeys.length} images`);
 ```
 **Performance Comparison:**
 | Method | Memory Usage | Best For | Supports Early Exit |
 |--------|-------------|----------|-------------------|
 | **Async Generator** | O(1) - constant | Most use cases, large datasets | Yes |
 | **Observable** | O(1) - constant | Reactive pipelines, RxJS apps | Yes |
 | **Cursor** | O(pageSize) | UI pagination, resumable ops | Yes |
 | **Array** | O(n) - grows with results | Small datasets (<10k items) | No |
 ### Bucket Watching
 Monitor your storage bucket for changes in real-time with the powerful `BucketWatcher`:
 ```typescript
 // Create a watcher for a specific prefix
 const watcher = bucket.createWatcher({
  prefix: 'uploads/',        // Watch files with this prefix
  pollIntervalMs: 3000,      // Check every 3 seconds
  includeInitial: false,     // Don't emit existing files on start
 });
 // RxJS Observable pattern (recommended for reactive apps)
 watcher.changeSubject.subscribe((change) => {
  if (change.type === 'add') {
    console.log('New file:', change.key);
  } else if (change.type === 'modify') {
    console.log('Modified:', change.key);
  } else if (change.type === 'delete') {
    console.log('Deleted:', change.key);
  }
 });
 // EventEmitter pattern (classic Node.js style)
 watcher.on('change', (change) => {
  console.log(`${change.type}: ${change.key}`);
 });
 watcher.on('error', (err) => {
  console.error('Watcher error:', err);
 });
 // Start watching
 await watcher.start();
 // Wait until watcher is ready (initial state built)
 await watcher.readyDeferred.promise;
 console.log('Watcher is now monitoring the bucket');
 // ... your application runs ...
 // Stop watching when done
 await watcher.stop();
 // Or use the alias:
 await watcher.close();
 ```
 #### Watcher Options
 ```typescript
 interface IBucketWatcherOptions {
  prefix?: string;           // Filter objects by prefix (default: '' = all)
  pollIntervalMs?: number;   // Polling interval in ms (default: 5000)
  bufferTimeMs?: number;     // Buffer events before emitting (for batching)
  includeInitial?: boolean;  // Emit existing files as 'add' on start (default: false)
  pageSize?: number;         // Objects per page when listing (default: 1000)
 }
 ```
 #### Buffered Events
 For high-frequency change environments, buffer events to reduce processing overhead:
 ```typescript
 const watcher = bucket.createWatcher({
  prefix: 'high-traffic/',
  pollIntervalMs: 1000,
  bufferTimeMs: 2000, // Collect events for 2 seconds before emitting
 });
 // Receive batched events as arrays
 watcher.changeSubject.subscribe((changes) => {
  if (Array.isArray(changes)) {
    console.log(`Batch of ${changes.length} changes:`);
    changes.forEach(c => console.log(`  - ${c.type}: ${c.key}`));
  }
 });
 await watcher.start();
 ```
 #### Change Event Structure
 ```typescript
 interface IStorageChangeEvent {
  type: 'add' | 'modify' | 'delete';
  key: string;           // Object key (path)
  bucket: string;        // Bucket name
  size?: number;         // File size (not present for deletes)
  etag?: string;         // ETag hash (not present for deletes)
  lastModified?: Date;   // Last modified date (not present for deletes)
 }
 ```
 #### Watch Use Cases
 - **Sync systems** - Detect changes to trigger synchronization
 - **Analytics** - Track file uploads/modifications in real-time
 - **Notifications** - Alert users when their files are ready
 - **Processing pipelines** - Trigger workflows on new file uploads
 - **Backup systems** - Detect changes for incremental backups
 - **Audit logs** - Track all bucket activity
 ### Directory Management
 SmartBucket provides powerful directory-like operations for organizing your files:
@@ -178,8 +474,8 @@ const baseDir = await bucket.getBaseDirectory();
 const directories = await baseDir.listDirectories();
 const files = await baseDir.listFiles();
-console.log(`📁 Found ${directories.length} directories`);
+console.log(`Found ${directories.length} directories`);
-console.log(`📄 Found ${files.length} files`);
+console.log(`Found ${files.length} files`);
 // Navigate subdirectories
 const subDir = await baseDir.getSubDirectoryByName('projects/2024');
@@ -192,27 +488,46 @@ await subDir.fastPut({
 // Get directory tree structure
 const tree = await subDir.getTreeArray();
-console.log('🌳 Directory tree:', tree);
+
 // Get directory path
 console.log('Base path:', subDir.getBasePath()); // "projects/2024/"
 // Create empty file as placeholder
 await subDir.createEmptyFile('placeholder.txt');
 // Check existence
 const fileExists = await subDir.fileExists({ path: 'report.pdf' });
 const dirExists = await baseDir.directoryExists('projects');
 ```
-### 🌊 Streaming Operations
+### Streaming Operations
-Handle large files efficiently with streaming:
+Handle large files efficiently with streaming support:
 #### Download Streams
 ```typescript
-// Node.js stream
+// Node.js stream (for file I/O, HTTP responses, etc.)
 const nodeStream = await bucket.fastGetStream(
  { path: 'large-video.mp4' },
  'nodestream'
 );
 // Pipe to file
 import * as fs from 'node:fs';
 nodeStream.pipe(fs.createWriteStream('local-video.mp4'));
-// Web stream (for modern environments)
+// Pipe to HTTP response
 app.get('/download', async (req, res) => {
  const stream = await bucket.fastGetStream(
    { path: 'file.pdf' },
    'nodestream'
  );
  res.setHeader('Content-Type', 'application/pdf');
  stream.pipe(res);
 });
 // Web stream (for modern browser/Deno environments)
 const webStream = await bucket.fastGetStream(
  { path: 'large-file.zip' },
  'webstream'
@@ -222,17 +537,16 @@ const webStream = await bucket.fastGetStream(
 #### Upload Streams
 ```typescript
 import * as fs from 'node:fs';
 // Stream upload from file
 const readStream = fs.createReadStream('big-data.csv');
 await bucket.fastPutStream({
  path: 'uploads/big-data.csv',
-  stream: readStream,
+  readableStream: readStream,
-  metadata: {
+  nativeMetadata: {
-    contentType: 'text/csv',
+    'content-type': 'text/csv',
-    userMetadata: {
+    'x-custom-header': 'my-value'
      uploadedBy: 'data-team',
      version: '2.0'
    }
  }
 });
 ```
@@ -242,118 +556,161 @@ await bucket.fastPutStream({
 ```typescript
 // Get file as ReplaySubject for reactive programming
 const replaySubject = await bucket.fastGetReplaySubject({
-  path: 'data/sensor-readings.json',
+  path: 'data/sensor-readings.json'
-  chunkSize: 1024
+});
 // Multiple subscribers can consume the same data
 replaySubject.subscribe({
  next: (chunk) => processChunk(chunk),
  complete: () => console.log('Stream complete')
 });
 replaySubject.subscribe({
-  next: (chunk) => processChunk(chunk),
+  next: (chunk) => logChunk(chunk)
  complete: () => console.log('✅ Stream complete')
 });
 ```
-### 🔒 File Locking
+### File Locking
-Prevent accidental modifications with file locking:
+Prevent concurrent modifications with built-in file locking:
 ```typescript
-const file = await bucket.getBaseDirectory()
+const baseDir = await bucket.getBaseDirectory();
-  .getFileStrict({ path: 'important-config.json' });
+const file = await baseDir.getFile({ path: 'important-config.json' });
 // Lock file for 10 minutes
 await file.lock({ timeoutMillis: 600000 });
 console.log('🔒 File locked');
-// Try to modify locked file (will throw error)
+// Check lock status via metadata
-try {
+const metadata = await file.getMetaData();
-  await file.delete();
+const isLocked = await metadata.checkLocked();
-} catch (error) {
+
-  console.log('❌ Cannot delete locked file');
+// Get lock info
-}
+const lockInfo = await metadata.getLockInfo();
 console.log(`Lock expires: ${new Date(lockInfo.expires)}`);
 // Unlock when done
 await file.unlock();
-console.log('🔓 File unlocked');
+
 // Force unlock (even if locked by another process)
 await file.unlock({ force: true });
 ```
-### 🏷️ Metadata Management
+**Lock use cases:**
 - Prevent concurrent writes during critical updates
 - Protect configuration files during deployment
 - Coordinate distributed workers
 - Ensure data consistency
-Attach and manage metadata for your files:
+### Metadata Management
 Attach and manage rich metadata for your files:
 ```typescript
-const file = await bucket.getBaseDirectory()
+const baseDir = await bucket.getBaseDirectory();
-  .getFileStrict({ path: 'document.pdf' });
+const file = await baseDir.getFile({ path: 'document.pdf' });
 // Get metadata handler
 const metadata = await file.getMetaData();
-// Set custom metadata
+// Store custom metadata (can be any JSON-serializable value)
-await metadata.setCustomMetaData({
+await metadata.storeCustomMetaData({
  key: 'author',
  value: 'John Doe'
 });
-await metadata.setCustomMetaData({
+await metadata.storeCustomMetaData({
-  key: 'department',
+  key: 'tags',
-  value: 'Engineering'
+  value: ['important', 'quarterly-report', '2024']
 });
 await metadata.storeCustomMetaData({
  key: 'workflow',
  value: { status: 'approved', approvedBy: 'jane@company.com' }
 });
 // Retrieve metadata
 const author = await metadata.getCustomMetaData({ key: 'author' });
 console.log(`📝 Author: ${author}`);
-// Get all metadata
+// Delete metadata
-const allMeta = await metadata.getAllCustomMetaData();
+await metadata.deleteCustomMetaData({ key: 'workflow' });
-console.log('📋 All metadata:', allMeta);
+
 // Check if file has any metadata
 const hasMetadata = await file.hasMetaData();
 // Get file type detection
 const fileType = await metadata.getFileType({ useFileExtension: true });
 // Get file type from magic bytes (more accurate)
 const detectedType = await metadata.getFileType({ useMagicBytes: true });
 // Get file size
 const size = await metadata.getSizeInBytes();
 ```
-### 🗑️ Trash & Recovery
+**Metadata use cases:**
 - Track file ownership and authorship
 - Add tags and categories for search
 - Store processing status or workflow state
 - Enable rich querying and filtering
 - Maintain audit trails
-SmartBucket includes an intelligent trash system for safe file deletion:
+### Trash & Recovery
 SmartBucket includes an intelligent trash system for safe file deletion and recovery:
 ```typescript
-const file = await bucket.getBaseDirectory()
+const baseDir = await bucket.getBaseDirectory();
-  .getFileStrict({ path: 'important-data.xlsx' });
+const file = await baseDir.getFile({ path: 'important-data.xlsx' });
 // Move to trash instead of permanent deletion
 await file.delete({ mode: 'trash' });
-console.log('🗑️ File moved to trash');
+
 // Permanent deletion (use with caution!)
 await file.delete({ mode: 'permanent' });
 // Access trash
 const trash = await bucket.getTrash();
 const trashDir = await trash.getTrashDir();
 const trashedFiles = await trashDir.listFiles();
 console.log(`📦 ${trashedFiles.length} files in trash`);
 // Restore from trash
-const trashedFile = await bucket.getBaseDirectory()
+const trashedFile = await baseDir.getFile({
-  .getFileStrict({ 
+  path: 'important-data.xlsx',
-    path: 'important-data.xlsx',
+  getFromTrash: true
-    getFromTrash: true
+});
  });
 await trashedFile.restore({ useOriginalPath: true });
 console.log('♻️ File restored successfully');
-// Permanent deletion from trash
+// Or restore to a different location
-await trash.emptyTrash();
+await trashedFile.restore({
-console.log('🧹 Trash emptied');
+  toPath: 'recovered/important-data.xlsx'
 });
 ```
-### ⚡ Advanced Features
+**Trash features:**
 - Recover accidentally deleted files
 - Preserves original path in metadata
 - Tracks deletion timestamp
 - List and inspect trashed files
 ### Advanced Features
 #### File Statistics
 ```typescript
 // Get detailed file statistics
 const stats = await bucket.fastStat({ path: 'document.pdf' });
-console.log(`📊 Size: ${stats.size} bytes`);
+console.log(`Size: ${stats.ContentLength} bytes`);
-console.log(`📅 Last modified: ${stats.lastModified}`);
+console.log(`Last modified: ${stats.LastModified}`);
-console.log(`🏷️ ETag: ${stats.etag}`);
+console.log(`ETag: ${stats.ETag}`);
 console.log(`Content type: ${stats.ContentType}`);
 ```
 #### Magic Bytes Detection
 Detect file types by examining the first bytes (useful for validation):
 ```typescript
 // Read first bytes for file type detection
 const magicBytes = await bucket.getMagicBytes({
@@ -362,27 +719,33 @@ const magicBytes = await bucket.getMagicBytes({
 });
 // Or from a File object
-const file = await bucket.getBaseDirectory()
+const baseDir = await bucket.getBaseDirectory();
-  .getFileStrict({ path: 'image.jpg' });
+const file = await baseDir.getFile({ path: 'image.jpg' });
 const magic = await file.getMagicBytes({ length: 4 });
-console.log(`🔮 Magic bytes: ${magic.toString('hex')}`);
+
 // Check file signatures
 if (magic[0] === 0xFF && magic[1] === 0xD8) {
  console.log('This is a JPEG image');
 } else if (magic[0] === 0x89 && magic[1] === 0x50) {
  console.log('This is a PNG image');
 }
 ```
 #### JSON Data Operations
 ```typescript
-const file = await bucket.getBaseDirectory()
+const baseDir = await bucket.getBaseDirectory();
-  .getFileStrict({ path: 'config.json' });
+const file = await baseDir.getFile({ path: 'config.json' });
 // Read JSON data
 const config = await file.getJsonData();
 console.log('⚙️ Config loaded:', config);
 // Update JSON data
 config.version = '2.0';
 config.updated = new Date().toISOString();
 config.features.push('newFeature');
 await file.writeJsonData(config);
 console.log('💾 Config updated');
 ```
 #### Directory & File Type Detection
@@ -393,9 +756,6 @@ const isDir = await bucket.isDirectory({ path: 'uploads/' });
 // Check if path is a file
 const isFile = await bucket.isFile({ path: 'uploads/document.pdf' });
 console.log(`Is directory: ${isDir ? '📁' : '❌'}`);
 console.log(`Is file: ${isFile ? '📄' : '❌'}`);
 ```
 #### Clean Bucket Contents
@@ -403,81 +763,175 @@ console.log(`Is file: ${isFile ? '📄' : '❌'}`);
 ```typescript
 // Remove all files and directories (use with caution!)
 await bucket.cleanAllContents();
 console.log('🧹 Bucket cleaned');
 ```
-### ☁️ Cloud Provider Support
+### Cloud Provider Support
-SmartBucket works seamlessly with:
+SmartBucket works seamlessly with all major S3-compatible providers:
- ✅ **AWS S3** - Full compatibility with S3 API
+| Provider | Status | Notes |
- ✅ **Google Cloud Storage** - Via S3-compatible API
+|----------|--------|-------|
- ✅ **MinIO** - Self-hosted S3-compatible storage
+| **AWS S3** | Supported | Native S3 API |
- ✅ **DigitalOcean Spaces** - S3-compatible object storage
+| **MinIO** | Supported | Self-hosted, perfect for development |
- ✅ **Backblaze B2** - Cost-effective cloud storage
+| **DigitalOcean Spaces** | Supported | Cost-effective S3-compatible |
- ✅ **Wasabi** - High-performance S3-compatible storage
+| **Backblaze B2** | Supported | Very affordable storage |
- ✅ **Any S3-compatible provider**
+| **Wasabi** | Supported | High-performance hot storage |
 | **Google Cloud Storage** | Supported | Via S3-compatible API |
 | **Cloudflare R2** | Supported | Zero egress fees |
 | **Any S3-compatible** | Supported | Works with any S3-compatible provider |
-The library automatically handles provider quirks and optimizes operations for each platform while maintaining a consistent API.
+**Configuration examples:**
 ### 🔧 Advanced Configuration
 ```typescript
-// Configure with custom options
+// AWS S3
-const smartBucket = new SmartBucket({
+const awsStorage = new SmartBucket({
-  accessKey: process.env.S3_ACCESS_KEY,
+  accessKey: process.env.AWS_ACCESS_KEY_ID,
-  accessSecret: process.env.S3_SECRET_KEY,
+  accessSecret: process.env.AWS_SECRET_ACCESS_KEY,
-  endpoint: process.env.S3_ENDPOINT,
+  endpoint: 's3.amazonaws.com',
-  port: 443,
+  region: 'us-east-1',
-  useSsl: true,
+  useSsl: true
  region: 'eu-central-1',
  // Additional S3 client options can be passed through
 });
-// Environment-based configuration
+// MinIO (local development)
 const minioStorage = new SmartBucket({
  accessKey: 'minioadmin',
  accessSecret: 'minioadmin',
  endpoint: 'localhost',
  port: 9000,
  useSsl: false
 });
 // DigitalOcean Spaces
 const doStorage = new SmartBucket({
  accessKey: process.env.DO_SPACES_KEY,
  accessSecret: process.env.DO_SPACES_SECRET,
  endpoint: 'nyc3.digitaloceanspaces.com',
  region: 'nyc3',
  useSsl: true
 });
 // Backblaze B2
 const b2Storage = new SmartBucket({
  accessKey: process.env.B2_KEY_ID,
  accessSecret: process.env.B2_APPLICATION_KEY,
  endpoint: 's3.us-west-002.backblazeb2.com',
  region: 'us-west-002',
  useSsl: true
 });
 // Cloudflare R2
 const r2Storage = new SmartBucket({
  accessKey: process.env.R2_ACCESS_KEY_ID,
  accessSecret: process.env.R2_SECRET_ACCESS_KEY,
  endpoint: `${process.env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
  region: 'auto',
  useSsl: true
 });
 ```
 ### Advanced Configuration
 ```typescript
 // Environment-based configuration with @push.rocks/qenv
 import { Qenv } from '@push.rocks/qenv';
 const qenv = new Qenv('./', './.nogit/');
 const smartBucket = new SmartBucket({
-  accessKey: await qenv.getEnvVarOnDemandStrict('S3_ACCESS_KEY'),
+  accessKey: await qenv.getEnvVarOnDemand('S3_ACCESS_KEY'),
-  accessSecret: await qenv.getEnvVarOnDemandStrict('S3_SECRET'),
+  accessSecret: await qenv.getEnvVarOnDemand('S3_SECRET'),
-  endpoint: await qenv.getEnvVarOnDemandStrict('S3_ENDPOINT'),
+  endpoint: await qenv.getEnvVarOnDemand('S3_ENDPOINT'),
  port: parseInt(await qenv.getEnvVarOnDemand('S3_PORT')),
  useSsl: await qenv.getEnvVarOnDemand('S3_USE_SSL') === 'true',
  region: await qenv.getEnvVarOnDemand('S3_REGION')
 });
 ```
-### 🧪 Testing
+### Testing
 SmartBucket is thoroughly tested. Run tests with:
 ```bash
 # Run all tests
 pnpm test
 # Run specific test file
 pnpm tstest test/test.watcher.node.ts --verbose
 # Run tests with log file
 pnpm test --logfile
 ```
-### 🤝 Best Practices
+### Error Handling Best Practices
 SmartBucket uses a **strict-by-default** approach - methods throw errors instead of returning null:
 ```typescript
 // Check existence first
 if (await bucket.fastExists({ path: 'file.txt' })) {
  const content = await bucket.fastGet({ path: 'file.txt' });
  process(content);
 }
 // Try/catch for expected failures
 try {
  const file = await bucket.fastGet({ path: 'might-not-exist.txt' });
  process(file);
 } catch (error) {
  console.log('File not found, using default');
  useDefault();
 }
 // Explicit overwrite control
 try {
  await bucket.fastPut({
    path: 'existing-file.txt',
    contents: 'new data',
    overwrite: false // Explicitly fail if exists
  });
 } catch (error) {
  console.log('File already exists');
 }
 ```
 ### Best Practices
 1. **Always use strict mode** for critical operations to catch errors early
-2. **Implement proper error handling** for network and permission issues
+2. **Check existence first** with `fastExists()`, `bucketExists()`, etc. before operations
-3. **Use streaming** for large files to optimize memory usage
+3. **Implement proper error handling** for network and permission issues
-4. **Leverage metadata** for organizing and searching files
+4. **Use streaming** for large files (>100MB) to optimize memory usage
-5. **Enable trash mode** for important data to prevent accidental loss
+5. **Leverage metadata** for organizing and searching files
-6. **Lock files** during critical operations to prevent race conditions
+6. **Enable trash mode** for important data to prevent accidental loss
-7. **Clean up resources** properly when done
+7. **Lock files** during critical operations to prevent race conditions
 8. **Use async generators** for listing large buckets to avoid memory issues
 9. **Set explicit overwrite flags** to prevent accidental file overwrites
 10. **Use the watcher** for real-time synchronization and event-driven architectures
 ### Performance Tips
 - **Listing**: Use async generators or cursors for buckets with >10,000 objects
 - **Uploads**: Use streams for files >100MB
 - **Downloads**: Use streams for files you'll process incrementally
 - **Metadata**: Cache metadata when reading frequently
 - **Locking**: Keep lock durations as short as possible
 - **Glob patterns**: Be specific to reduce objects scanned
 - **Watching**: Use appropriate `pollIntervalMs` based on your change frequency
 ## License and Legal Information
-This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. 
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 ### Trademarks
-This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
 Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
 ### Company Information
 Task Venture Capital GmbH
-Registered at District court Bremen HRB 35230 HB, Germany
+Registered at District Court Bremen HRB 35230 HB, Germany
-For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
 By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.
--- a/test/test.listing.node+deno.ts
+++ b/test/test.listing.node+deno.ts
@@ -0,0 +1,298 @@
 // test.listing.node+deno.ts - Tests for memory-efficient listing methods
 import { tap, expect } from '@git.zone/tstest/tapbundle';
 import * as smartbucket from '../ts/index.js';
 // Get test configuration
 import * as qenv from '@push.rocks/qenv';
 const testQenv = new qenv.Qenv('./', './.nogit/');
 // Test bucket reference
 let testBucket: smartbucket.Bucket;
 let testSmartbucket: smartbucket.SmartBucket;
 // Setup: Create test bucket and populate with test data
 tap.test('should create valid smartbucket and bucket', async () => {
  testSmartbucket = new smartbucket.SmartBucket({
    accessKey: await testQenv.getEnvVarOnDemand('S3_ACCESSKEY') as string,
    accessSecret: await testQenv.getEnvVarOnDemand('S3_SECRETKEY') as string,
    endpoint: await testQenv.getEnvVarOnDemand('S3_ENDPOINT') as string,
    port: parseInt(await testQenv.getEnvVarOnDemand('S3_PORT') as string),
    useSsl: false,
  });
  testBucket = await smartbucket.Bucket.getBucketByName(
    testSmartbucket,
    await testQenv.getEnvVarOnDemand('S3_BUCKET')  as string
  );
  expect(testBucket).toBeInstanceOf(smartbucket.Bucket);
 });
 tap.test('should clean bucket and create test data for listing tests', async () => {
  // Clean bucket first
  await testBucket.cleanAllContents();
  // Create test structure:
  // npm/packages/foo/index.json
  // npm/packages/foo/1.0.0.tgz
  // npm/packages/bar/index.json
  // npm/packages/bar/2.0.0.tgz
  // oci/blobs/sha256-abc.tar
  // oci/blobs/sha256-def.tar
  // oci/manifests/latest.json
  // docs/readme.md
  // docs/api.md
  const testFiles = [
    'npm/packages/foo/index.json',
    'npm/packages/foo/1.0.0.tgz',
    'npm/packages/bar/index.json',
    'npm/packages/bar/2.0.0.tgz',
    'oci/blobs/sha256-abc.tar',
    'oci/blobs/sha256-def.tar',
    'oci/manifests/latest.json',
    'docs/readme.md',
    'docs/api.md',
  ];
  for (const filePath of testFiles) {
    await testBucket.fastPut({
      path: filePath,
      contents: `test content for ${filePath}`,
    });
  }
 });
 // ==========================
 // Async Generator Tests
 // ==========================
 tap.test('listAllObjects should iterate all objects with prefix', async () => {
  const keys: string[] = [];
  for await (const key of testBucket.listAllObjects('npm/')) {
    keys.push(key);
  }
  expect(keys.length).toEqual(4);
  expect(keys).toContain('npm/packages/foo/index.json');
  expect(keys).toContain('npm/packages/bar/2.0.0.tgz');
 });
 tap.test('listAllObjects should support early termination', async () => {
  let count = 0;
  for await (const key of testBucket.listAllObjects('')) {
    count++;
    if (count >= 3) break; // Early exit
  }
  expect(count).toEqual(3);
 });
 tap.test('listAllObjects without prefix should list all objects', async () => {
  const keys: string[] = [];
  for await (const key of testBucket.listAllObjects()) {
    keys.push(key);
  }
  expect(keys.length).toBeGreaterThanOrEqual(9);
 });
 // ==========================
 // Observable Tests
 // ==========================
 tap.test('listAllObjectsObservable should emit all objects', async () => {
  const keys: string[] = [];
  await new Promise<void>((resolve, reject) => {
    testBucket.listAllObjectsObservable('oci/')
      .subscribe({
        next: (key) => keys.push(key),
        error: (err) => reject(err),
        complete: () => resolve(),
      });
  });
  expect(keys.length).toEqual(3);
  expect(keys).toContain('oci/blobs/sha256-abc.tar');
  expect(keys).toContain('oci/manifests/latest.json');
 });
 tap.test('listAllObjectsObservable should support RxJS operators', async () => {
  const jsonFiles: string[] = [];
  await new Promise<void>((resolve, reject) => {
    testBucket.listAllObjectsObservable('npm/')
      .subscribe({
        next: (key: string) => {
          if (key.endsWith('.json')) {
            jsonFiles.push(key);
          }
        },
        error: (err: any) => reject(err),
        complete: () => resolve(),
      });
  });
  expect(jsonFiles.length).toEqual(2);
  expect(jsonFiles.every((k) => k.endsWith('.json'))).toBeTrue();
 });
 // ==========================
 // Cursor Tests
 // ==========================
 tap.test('createCursor should allow manual pagination', async () => {
  const cursor = testBucket.createCursor('npm/', { pageSize: 2 });
  // First page
  const page1 = await cursor.next();
  expect(page1.keys.length).toEqual(2);
  expect(page1.done).toBeFalse();
  // Second page
  const page2 = await cursor.next();
  expect(page2.keys.length).toEqual(2);
  expect(page2.done).toBeTrue();
 });
 tap.test('cursor.hasMore() should accurately track state', async () => {
  const cursor = testBucket.createCursor('docs/', { pageSize: 10 });
  expect(cursor.hasMore()).toBeTrue();
  await cursor.next(); // Should get all docs files
  expect(cursor.hasMore()).toBeFalse();
 });
 tap.test('cursor.reset() should allow re-iteration', async () => {
  const cursor = testBucket.createCursor('docs/');
  const firstRun = await cursor.next();
  expect(firstRun.keys.length).toBeGreaterThan(0);
  cursor.reset();
  expect(cursor.hasMore()).toBeTrue();
  const secondRun = await cursor.next();
  expect(secondRun.keys).toEqual(firstRun.keys);
 });
 tap.test('cursor should support save/restore with token', async () => {
  const cursor1 = testBucket.createCursor('npm/', { pageSize: 2 });
  await cursor1.next(); // Advance cursor
  const token = cursor1.getToken();
  expect(token).toBeDefined();
  // Create new cursor and restore state
  const cursor2 = testBucket.createCursor('npm/', { pageSize: 2 });
  cursor2.setToken(token);
  const page = await cursor2.next();
  expect(page.keys.length).toBeGreaterThan(0);
 });
 // ==========================
 // findByGlob Tests
 // ==========================
 tap.test('findByGlob should match simple patterns', async () => {
  const matches: string[] = [];
  for await (const key of testBucket.findByGlob('**/*.json')) {
    matches.push(key);
  }
  expect(matches.length).toEqual(3); // foo/index.json, bar/index.json, latest.json
  expect(matches.every((k) => k.endsWith('.json'))).toBeTrue();
 });
 tap.test('findByGlob should match specific path patterns', async () => {
  const matches: string[] = [];
  for await (const key of testBucket.findByGlob('npm/packages/*/index.json')) {
    matches.push(key);
  }
  expect(matches.length).toEqual(2);
  expect(matches).toContain('npm/packages/foo/index.json');
  expect(matches).toContain('npm/packages/bar/index.json');
 });
 tap.test('findByGlob should match wildcard patterns', async () => {
  const matches: string[] = [];
  for await (const key of testBucket.findByGlob('oci/blobs/*')) {
    matches.push(key);
  }
  expect(matches.length).toEqual(2);
  expect(matches.every((k) => k.startsWith('oci/blobs/'))).toBeTrue();
 });
 // ==========================
 // listAllObjectsArray Tests
 // ==========================
 tap.test('listAllObjectsArray should collect all keys into array', async () => {
  const keys = await testBucket.listAllObjectsArray('docs/');
  expect(Array.isArray(keys)).toBeTrue();
  expect(keys.length).toEqual(2);
  expect(keys).toContain('docs/readme.md');
  expect(keys).toContain('docs/api.md');
 });
 tap.test('listAllObjectsArray without prefix should return all objects', async () => {
  const keys = await testBucket.listAllObjectsArray();
  expect(keys.length).toBeGreaterThanOrEqual(9);
 });
 // ==========================
 // Performance/Edge Case Tests
 // ==========================
 tap.test('should handle empty prefix results gracefully', async () => {
  const keys: string[] = [];
  for await (const key of testBucket.listAllObjects('nonexistent/')) {
    keys.push(key);
  }
  expect(keys.length).toEqual(0);
 });
 tap.test('cursor should handle empty results', async () => {
  const cursor = testBucket.createCursor('nonexistent/');
  const result = await cursor.next();
  expect(result.keys.length).toEqual(0);
  expect(result.done).toBeTrue();
  expect(cursor.hasMore()).toBeFalse();
 });
 tap.test('observable should complete immediately on empty results', async () => {
  let completed = false;
  let count = 0;
  await new Promise<void>((resolve, reject) => {
    testBucket.listAllObjectsObservable('nonexistent/')
      .subscribe({
        next: () => count++,
        error: (err) => reject(err),
        complete: () => {
          completed = true;
          resolve();
        },
      });
  });
  expect(count).toEqual(0);
  expect(completed).toBeTrue();
 });
 // Cleanup
 tap.test('should clean up test data', async () => {
  await testBucket.cleanAllContents();
 });
 export default tap.start();
--- a/test/test.local.node+deno.ts
+++ b/test/test.local.node+deno.ts
@@ -0,0 +1,76 @@
 import { expect, tap } from '@git.zone/tstest/tapbundle';
 import * as plugins from '../ts/plugins.js';
 import * as smartbucket from '../ts/index.js';
 class FakeStorageClient {
  private callIndex = 0;
  constructor(private readonly pages: Array<Partial<plugins.s3.ListObjectsV2Output>>) {}
  public async send(_command: any) {
    const page = this.pages[this.callIndex] || { Contents: [], CommonPrefixes: [], IsTruncated: false };
    this.callIndex += 1;
    return page;
  }
 }
 tap.test('MetaData.hasMetaData should return false when metadata file does not exist', async () => {
  const fakeFile = {
    name: 'file.txt',
    parentDirectoryRef: {
      async getFile() {
        throw new Error(`File not found at path 'file.txt.metadata'`);
      },
    },
  } as unknown as smartbucket.File;
  const hasMetaData = await smartbucket.MetaData.hasMetaData({ file: fakeFile });
  expect(hasMetaData).toBeFalse();
 });
 tap.test('getSubDirectoryByName should create correct parent chain for new nested directories', async () => {
  const fakeSmartbucket = { storageClient: new FakeStorageClient([{ Contents: [], CommonPrefixes: [] }]) } as unknown as smartbucket.SmartBucket;
  const bucket = new smartbucket.Bucket(fakeSmartbucket, 'test-bucket');
  const baseDirectory = new smartbucket.Directory(bucket, null as any, '');
  const nestedDirectory = await baseDirectory.getSubDirectoryByName('level1/level2', { getEmptyDirectory: true });
  expect(nestedDirectory.name).toEqual('level2');
  expect(nestedDirectory.parentDirectoryRef.name).toEqual('level1');
  expect(nestedDirectory.getBasePath()).toEqual('level1/level2/');
 });
 tap.test('listFiles should aggregate results across paginated ListObjectsV2 responses', async () => {
  const firstPage = {
    Contents: Array.from({ length: 1000 }, (_, index) => ({ Key: `file-${index}` })),
    IsTruncated: true,
    NextContinuationToken: 'token-1',
  };
  const secondPage = {
    Contents: Array.from({ length: 200 }, (_, index) => ({ Key: `file-${1000 + index}` })),
    IsTruncated: false,
  };
  const fakeSmartbucket = { storageClient: new FakeStorageClient([firstPage, secondPage]) } as unknown as smartbucket.SmartBucket;
  const bucket = new smartbucket.Bucket(fakeSmartbucket, 'test-bucket');
  const baseDirectory = new smartbucket.Directory(bucket, null as any, '');
  const files = await baseDirectory.listFiles();
  expect(files.length).toEqual(1200);
 });
 tap.test('listDirectories should aggregate CommonPrefixes across pagination', async () => {
  const fakeSmartbucket = {
    storageClient: new FakeStorageClient([
      { CommonPrefixes: [{ Prefix: 'dirA/' }], IsTruncated: true, NextContinuationToken: 'token-1' },
      { CommonPrefixes: [{ Prefix: 'dirB/' }], IsTruncated: false },
    ]),
  } as unknown as smartbucket.SmartBucket;
  const bucket = new smartbucket.Bucket(fakeSmartbucket, 'test-bucket');
  const baseDirectory = new smartbucket.Directory(bucket, null as any, '');
  const directories = await baseDirectory.listDirectories();
  expect(directories.map((d) => d.name)).toEqual(['dirA', 'dirB']);
 });
 export default tap.start();
--- a/test/test.node+deno.ts
+++ b/test/test.node+deno.ts
@@ -12,13 +12,16 @@ let baseDirectory: smartbucket.Directory;
 tap.test('should create a valid smartbucket', async () => {
  testSmartbucket = new smartbucket.SmartBucket({
    accessKey: await testQenv.getEnvVarOnDemandStrict('S3_ACCESSKEY'),
-    accessSecret: await testQenv.getEnvVarOnDemandStrict('S3_ACCESSSECRET'),
+    accessSecret: await testQenv.getEnvVarOnDemandStrict('S3_SECRETKEY'),
    endpoint: await testQenv.getEnvVarOnDemandStrict('S3_ENDPOINT'),
    port: parseInt(await testQenv.getEnvVarOnDemandStrict('S3_PORT')),
    useSsl: false,
  });
  expect(testSmartbucket).toBeInstanceOf(smartbucket.SmartBucket);
-  myBucket = await testSmartbucket.getBucketByName(await testQenv.getEnvVarOnDemandStrict('S3_BUCKET'),);
+  const bucketName = await testQenv.getEnvVarOnDemandStrict('S3_BUCKET');
  myBucket = await testSmartbucket.getBucketByName(bucketName);
  expect(myBucket).toBeInstanceOf(smartbucket.Bucket);
-  expect(myBucket.name).toEqual('test-pushrocks-smartbucket');
+  expect(myBucket.name).toEqual(bucketName);
 });
 tap.test('should clean all contents', async () => {
--- a/test/test.trash.node+deno.ts
+++ b/test/test.trash.node+deno.ts
@@ -13,13 +13,15 @@ let baseDirectory: smartbucket.Directory;
 tap.test('should create a valid smartbucket', async () => {
  testSmartbucket = new smartbucket.SmartBucket({
    accessKey: await testQenv.getEnvVarOnDemandStrict('S3_ACCESSKEY'),
-    accessSecret: await testQenv.getEnvVarOnDemandStrict('S3_ACCESSSECRET'),
+    accessSecret: await testQenv.getEnvVarOnDemandStrict('S3_SECRETKEY'),
    endpoint: await testQenv.getEnvVarOnDemandStrict('S3_ENDPOINT'),
    port: parseInt(await testQenv.getEnvVarOnDemandStrict('S3_PORT')),
    useSsl: false,
  });
  expect(testSmartbucket).toBeInstanceOf(smartbucket.SmartBucket);
-  myBucket = await testSmartbucket.getBucketByName(await testQenv.getEnvVarOnDemandStrict('S3_BUCKET'),);
+  const bucketName = await testQenv.getEnvVarOnDemandStrict('S3_BUCKET');
  myBucket = await testSmartbucket.getBucketByName(bucketName);
  expect(myBucket).toBeInstanceOf(smartbucket.Bucket);
  expect(myBucket.name).toEqual('test-pushrocks-smartbucket');
 });
 tap.test('should clean all contents', async () => {
--- a/test/test.watcher.node.ts
+++ b/test/test.watcher.node.ts
@@ -0,0 +1,410 @@
 // test.watcher.node.ts - Tests for BucketWatcher
 import { tap, expect } from '@git.zone/tstest/tapbundle';
 import * as smartbucket from '../ts/index.js';
 import type { IStorageChangeEvent } from '../ts/interfaces.js';
 // Get test configuration
 import * as qenv from '@push.rocks/qenv';
 const testQenv = new qenv.Qenv('./', './.nogit/');
 // Test bucket reference
 let testBucket: smartbucket.Bucket;
 let testSmartbucket: smartbucket.SmartBucket;
 // Setup: Create test bucket
 tap.test('should create valid smartbucket and bucket', async () => {
  testSmartbucket = new smartbucket.SmartBucket({
    accessKey: await testQenv.getEnvVarOnDemand('S3_ACCESSKEY'),
    accessSecret: await testQenv.getEnvVarOnDemand('S3_SECRETKEY'),
    endpoint: await testQenv.getEnvVarOnDemand('S3_ENDPOINT'),
    port: parseInt(await testQenv.getEnvVarOnDemand('S3_PORT')),
    useSsl: false,
  });
  testBucket = await smartbucket.Bucket.getBucketByName(
    testSmartbucket,
    await testQenv.getEnvVarOnDemand('S3_BUCKET')
  );
  expect(testBucket).toBeInstanceOf(smartbucket.Bucket);
 });
 tap.test('should clean bucket for watcher tests', async () => {
  await testBucket.cleanAllContents();
 });
 // ==========================
 // Basic Watcher Tests
 // ==========================
 tap.test('should create watcher with default options', async () => {
  const watcher = testBucket.createWatcher();
  expect(watcher).toBeInstanceOf(smartbucket.BucketWatcher);
  expect(watcher.changeSubject).toBeDefined();
 });
 tap.test('should create watcher with custom options', async () => {
  const watcher = testBucket.createWatcher({
    prefix: 'test/',
    pollIntervalMs: 2000,
    includeInitial: true,
  });
  expect(watcher).toBeInstanceOf(smartbucket.BucketWatcher);
 });
 // ==========================
 // Add Event Detection Tests
 // ==========================
 tap.test('should detect add events for new files', async () => {
  const events: IStorageChangeEvent[] = [];
  const watcher = testBucket.createWatcher({
    prefix: 'watcher-test/',
    pollIntervalMs: 500,
  });
  watcher.changeSubject.subscribe((event) => {
    if (!Array.isArray(event)) {
      events.push(event);
    }
  });
  await watcher.start();
  await watcher.readyDeferred.promise;
  // Create a new file
  await testBucket.fastPut({
    path: 'watcher-test/new-file.txt',
    contents: 'test content',
  });
  // Wait for poll to detect the change
  await new Promise((resolve) => setTimeout(resolve, 1200));
  await watcher.stop();
  expect(events.length).toBeGreaterThanOrEqual(1);
  const addEvent = events.find((e) => e.type === 'add' && e.key === 'watcher-test/new-file.txt');
  expect(addEvent).toBeDefined();
  expect(addEvent!.bucket).toEqual(testBucket.name);
 });
 // ==========================
 // Modify Event Detection Tests
 // ==========================
 tap.test('should detect modify events for changed files', async () => {
  const events: IStorageChangeEvent[] = [];
  const watcher = testBucket.createWatcher({
    prefix: 'watcher-test/',
    pollIntervalMs: 500,
  });
  watcher.changeSubject.subscribe((event) => {
    if (!Array.isArray(event)) {
      events.push(event);
    }
  });
  await watcher.start();
  await watcher.readyDeferred.promise;
  // Modify the file
  await testBucket.fastPut({
    path: 'watcher-test/new-file.txt',
    contents: 'modified content with different size',
    overwrite: true,
  });
  // Wait for poll to detect the change
  await new Promise((resolve) => setTimeout(resolve, 1200));
  await watcher.stop();
  expect(events.length).toBeGreaterThanOrEqual(1);
  const modifyEvent = events.find((e) => e.type === 'modify' && e.key === 'watcher-test/new-file.txt');
  expect(modifyEvent).toBeDefined();
 });
 // ==========================
 // Delete Event Detection Tests
 // ==========================
 tap.test('should detect delete events for removed files', async () => {
  const events: IStorageChangeEvent[] = [];
  const watcher = testBucket.createWatcher({
    prefix: 'watcher-test/',
    pollIntervalMs: 500,
  });
  watcher.changeSubject.subscribe((event) => {
    if (!Array.isArray(event)) {
      events.push(event);
    }
  });
  await watcher.start();
  await watcher.readyDeferred.promise;
  // Delete the file
  await testBucket.fastRemove({ path: 'watcher-test/new-file.txt' });
  // Wait for poll to detect the change
  await new Promise((resolve) => setTimeout(resolve, 1200));
  await watcher.stop();
  expect(events.length).toBeGreaterThanOrEqual(1);
  const deleteEvent = events.find((e) => e.type === 'delete' && e.key === 'watcher-test/new-file.txt');
  expect(deleteEvent).toBeDefined();
 });
 // ==========================
 // Initial State Tests
 // ==========================
 tap.test('should emit initial state as add events when includeInitial is true', async () => {
  // First, create some test files
  await testBucket.fastPut({
    path: 'watcher-initial/file1.txt',
    contents: 'content 1',
  });
  await testBucket.fastPut({
    path: 'watcher-initial/file2.txt',
    contents: 'content 2',
  });
  const events: IStorageChangeEvent[] = [];
  const watcher = testBucket.createWatcher({
    prefix: 'watcher-initial/',
    pollIntervalMs: 10000, // Long interval - we only care about initial events
    includeInitial: true,
  });
  watcher.changeSubject.subscribe((event) => {
    if (!Array.isArray(event)) {
      events.push(event);
    }
  });
  await watcher.start();
  await watcher.readyDeferred.promise;
  // Give a moment for events to propagate
  await new Promise((resolve) => setTimeout(resolve, 100));
  await watcher.stop();
  expect(events.length).toEqual(2);
  expect(events.every((e) => e.type === 'add')).toBeTrue();
  expect(events.some((e) => e.key === 'watcher-initial/file1.txt')).toBeTrue();
  expect(events.some((e) => e.key === 'watcher-initial/file2.txt')).toBeTrue();
 });
 // ==========================
 // EventEmitter Pattern Tests
 // ==========================
 tap.test('should emit events via EventEmitter pattern', async () => {
  const events: IStorageChangeEvent[] = [];
  const watcher = testBucket.createWatcher({
    prefix: 'watcher-emitter/',
    pollIntervalMs: 500,
  });
  watcher.on('change', (event: IStorageChangeEvent) => {
    events.push(event);
  });
  await watcher.start();
  await watcher.readyDeferred.promise;
  // Create a new file
  await testBucket.fastPut({
    path: 'watcher-emitter/emitter-test.txt',
    contents: 'test content',
  });
  // Wait for poll to detect the change
  await new Promise((resolve) => setTimeout(resolve, 1200));
  await watcher.stop();
  expect(events.length).toBeGreaterThanOrEqual(1);
  expect(events[0].type).toEqual('add');
 });
 // ==========================
 // Buffered Events Tests
 // ==========================
 tap.test('should buffer events when bufferTimeMs is set', async () => {
  const bufferedEvents: (IStorageChangeEvent | IStorageChangeEvent[])[] = [];
  const watcher = testBucket.createWatcher({
    prefix: 'watcher-buffer/',
    pollIntervalMs: 200,
    bufferTimeMs: 1000,
  });
  watcher.changeSubject.subscribe((event) => {
    bufferedEvents.push(event);
  });
  await watcher.start();
  await watcher.readyDeferred.promise;
  // Create multiple files quickly
  await testBucket.fastPut({
    path: 'watcher-buffer/file1.txt',
    contents: 'content 1',
  });
  await testBucket.fastPut({
    path: 'watcher-buffer/file2.txt',
    contents: 'content 2',
  });
  await testBucket.fastPut({
    path: 'watcher-buffer/file3.txt',
    contents: 'content 3',
  });
  // Wait for buffer to emit
  await new Promise((resolve) => setTimeout(resolve, 1500));
  await watcher.stop();
  // With buffering, events should come as arrays
  expect(bufferedEvents.length).toBeGreaterThanOrEqual(1);
  // At least one buffered emission should contain multiple events
  const hasBufferedArray = bufferedEvents.some(
    (e) => Array.isArray(e) && e.length >= 1
  );
  expect(hasBufferedArray).toBeTrue();
 });
 // ==========================
 // Error Handling Tests
 // ==========================
 tap.test('should emit error events on error', async () => {
  const errors: Error[] = [];
  const watcher = testBucket.createWatcher({
    prefix: 'watcher-error/',
    pollIntervalMs: 500,
  });
  watcher.on('error', (err: Error) => {
    errors.push(err);
  });
  await watcher.start();
  await watcher.readyDeferred.promise;
  // Note: Triggering actual S3 errors is tricky in tests.
  // We just verify the error handler is properly attached.
  await watcher.stop();
  // No errors expected in normal operation
  expect(errors.length).toEqual(0);
 });
 // ==========================
 // Graceful Stop Tests
 // ==========================
 tap.test('should stop gracefully with stop()', async () => {
  const watcher = testBucket.createWatcher({
    prefix: 'watcher-stop/',
    pollIntervalMs: 100,
  });
  await watcher.start();
  await watcher.readyDeferred.promise;
  // Let it poll a few times
  await new Promise((resolve) => setTimeout(resolve, 300));
  // Stop should complete without errors
  await watcher.stop();
  // Watcher should not poll after stop
  const eventsCaptured: IStorageChangeEvent[] = [];
  watcher.on('change', (event: IStorageChangeEvent) => {
    eventsCaptured.push(event);
  });
  // Create a file after stop
  await testBucket.fastPut({
    path: 'watcher-stop/after-stop.txt',
    contents: 'should not be detected',
  });
  await new Promise((resolve) => setTimeout(resolve, 200));
  // No events should be captured after stop
  expect(eventsCaptured.length).toEqual(0);
 });
 tap.test('should stop gracefully with close() alias', async () => {
  const watcher = testBucket.createWatcher({
    prefix: 'watcher-close/',
    pollIntervalMs: 100,
  });
  await watcher.start();
  await watcher.readyDeferred.promise;
  // close() should work as alias for stop()
  await watcher.close();
 });
 // ==========================
 // Prefix Filtering Tests
 // ==========================
 tap.test('should only detect changes within specified prefix', async () => {
  const events: IStorageChangeEvent[] = [];
  const watcher = testBucket.createWatcher({
    prefix: 'watcher-prefix-a/',
    pollIntervalMs: 500,
  });
  watcher.changeSubject.subscribe((event) => {
    if (!Array.isArray(event)) {
      events.push(event);
    }
  });
  await watcher.start();
  await watcher.readyDeferred.promise;
  // Create file in watched prefix
  await testBucket.fastPut({
    path: 'watcher-prefix-a/watched.txt',
    contents: 'watched content',
  });
  // Create file outside watched prefix
  await testBucket.fastPut({
    path: 'watcher-prefix-b/unwatched.txt',
    contents: 'unwatched content',
  });
  // Wait for poll
  await new Promise((resolve) => setTimeout(resolve, 1200));
  await watcher.stop();
  // Should only see the file in watcher-prefix-a/
  expect(events.length).toEqual(1);
  expect(events[0].key).toEqual('watcher-prefix-a/watched.txt');
 });
 // ==========================
 // Cleanup
 // ==========================
 tap.test('should clean up test data', async () => {
  await testBucket.cleanAllContents();
 });
 export default tap.start();
--- a/ts/00_commitinfo_data.ts
+++ b/ts/00_commitinfo_data.ts
@@ -3,6 +3,6 @@
 */
 export const commitinfo = {
  name: '@push.rocks/smartbucket',
-  version: '4.0.0',
+  version: '4.5.1',
  description: 'A TypeScript library providing a cloud-agnostic interface for managing object storage with functionalities like bucket management, file and directory operations, and advanced features such as metadata handling and file locking.'
 }
--- a/ts/classes.bucket.ts
+++ b/ts/classes.bucket.ts
@@ -7,16 +7,18 @@ import { SmartBucket } from './classes.smartbucket.js';
 import { Directory } from './classes.directory.js';
 import { File } from './classes.file.js';
 import { Trash } from './classes.trash.js';
 import { ListCursor, type IListCursorOptions } from './classes.listcursor.js';
 import { BucketWatcher } from './classes.watcher.js';
 /**
 * The bucket class exposes the basic functionality of a bucket.
 * The functions of the bucket alone are enough to
- * operate in S3 basic fashion on blobs of data.
+ * operate on blobs of data in an S3-compatible object store.
 */
 export class Bucket {
  public static async getBucketByName(smartbucketRef: SmartBucket, bucketNameArg: string): Promise<Bucket> {
    const command = new plugins.s3.ListBucketsCommand({});
-    const buckets = await smartbucketRef.s3Client.send(command);
+    const buckets = await smartbucketRef.storageClient.send(command);
    const foundBucket = buckets.Buckets!.find((bucket) => bucket.Name === bucketNameArg);
    if (foundBucket) {
@@ -30,13 +32,13 @@ export class Bucket {
  public static async createBucketByName(smartbucketRef: SmartBucket, bucketName: string) {
    const command = new plugins.s3.CreateBucketCommand({ Bucket: bucketName });
-    await smartbucketRef.s3Client.send(command).catch((e) => console.log(e));
+    await smartbucketRef.storageClient.send(command);
    return new Bucket(smartbucketRef, bucketName);
  }
  public static async removeBucketByName(smartbucketRef: SmartBucket, bucketName: string) {
    const command = new plugins.s3.DeleteBucketCommand({ Bucket: bucketName });
-    await smartbucketRef.s3Client.send(command).catch((e) => console.log(e));
+    await smartbucketRef.storageClient.send(command);
  }
  public smartbucketRef: SmartBucket;
@@ -110,7 +112,7 @@ export class Bucket {
        Key: reducedPath,
        Body: optionsArg.contents,
      });
-      await this.smartbucketRef.s3Client.send(command);
+      await this.smartbucketRef.storageClient.send(command);
      console.log(`Object '${reducedPath}' has been successfully stored in bucket '${this.name}'.`);
      const parsedPath = plugins.path.parse(reducedPath);
@@ -170,7 +172,7 @@ export class Bucket {
      Bucket: this.name,
      Key: optionsArg.path,
    });
-    const response = await this.smartbucketRef.s3Client.send(command);
+    const response = await this.smartbucketRef.storageClient.send(command);
    const replaySubject = new plugins.smartrx.rxjs.ReplaySubject<Buffer>();
    // Convert the stream to a format that supports piping
@@ -214,7 +216,7 @@ export class Bucket {
      Bucket: this.name,
      Key: optionsArg.path,
    });
-    const response = await this.smartbucketRef.s3Client.send(command);
+    const response = await this.smartbucketRef.storageClient.send(command);
    const stream = response.Body as any; // SdkStreamMixin includes readable stream
    const duplexStream = new plugins.smartstream.SmartDuplex<Buffer, Buffer>({
@@ -270,7 +272,7 @@ export class Bucket {
        Body: optionsArg.readableStream,
        Metadata: optionsArg.nativeMetadata,
      });
-      await this.smartbucketRef.s3Client.send(command);
+      await this.smartbucketRef.storageClient.send(command);
      console.log(
        `Object '${optionsArg.path}' has been successfully stored in bucket '${this.name}'.`
@@ -295,7 +297,7 @@ export class Bucket {
      const targetBucketName = optionsArg.targetBucket ? optionsArg.targetBucket.name : this.name;
      // Retrieve current object information to use in copy conditions
-      const currentObjInfo = await this.smartbucketRef.s3Client.send(
+      const currentObjInfo = await this.smartbucketRef.storageClient.send(
        new plugins.s3.HeadObjectCommand({
          Bucket: this.name,
          Key: optionsArg.sourcePath,
@@ -317,7 +319,7 @@ export class Bucket {
        Metadata: newNativeMetadata,
        MetadataDirective: optionsArg.deleteExistingNativeMetadata ? 'REPLACE' : 'COPY',
      });
-      await this.smartbucketRef.s3Client.send(command);
+      await this.smartbucketRef.storageClient.send(command);
    } catch (err) {
      console.error('Error updating metadata:', err);
      throw err; // rethrow to allow caller to handle
@@ -377,7 +379,7 @@ export class Bucket {
      Bucket: this.name,
      Key: optionsArg.path,
    });
-    await this.smartbucketRef.s3Client.send(command);
+    await this.smartbucketRef.storageClient.send(command);
  }
  /**
@@ -391,7 +393,7 @@ export class Bucket {
        Bucket: this.name,
        Key: optionsArg.path,
      });
-      await this.smartbucketRef.s3Client.send(command);
+      await this.smartbucketRef.storageClient.send(command);
      console.log(`Object '${optionsArg.path}' exists in bucket '${this.name}'.`);
      return true;
    } catch (error: any) {
@@ -409,7 +411,7 @@ export class Bucket {
   * deletes this bucket
   */
  public async delete() {
-    await this.smartbucketRef.s3Client.send(
+    await this.smartbucketRef.storageClient.send(
      new plugins.s3.DeleteBucketCommand({ Bucket: this.name })
    );
  }
@@ -420,7 +422,7 @@ export class Bucket {
      Bucket: this.name,
      Key: checkPath,
    });
-    return this.smartbucketRef.s3Client.send(command);
+    return this.smartbucketRef.storageClient.send(command);
  }
  public async isDirectory(pathDescriptor: interfaces.IPathDecriptor): Promise<boolean> {
@@ -430,7 +432,7 @@ export class Bucket {
      Prefix: checkPath,
      Delimiter: '/',
    });
-    const { CommonPrefixes } = await this.smartbucketRef.s3Client.send(command);
+    const { CommonPrefixes } = await this.smartbucketRef.storageClient.send(command);
    return !!CommonPrefixes && CommonPrefixes.length > 0;
  }
@@ -441,7 +443,7 @@ export class Bucket {
      Prefix: checkPath,
      Delimiter: '/',
    });
-    const { Contents } = await this.smartbucketRef.s3Client.send(command);
+    const { Contents } = await this.smartbucketRef.storageClient.send(command);
    return !!Contents && Contents.length > 0;
  }
@@ -452,7 +454,7 @@ export class Bucket {
        Key: optionsArg.path,
        Range: `bytes=0-${optionsArg.length - 1}`,
      });
-      const response = await this.smartbucketRef.s3Client.send(command);
+      const response = await this.smartbucketRef.storageClient.send(command);
      const chunks: Buffer[] = [];
      const stream = response.Body as any; // SdkStreamMixin includes readable stream
@@ -469,6 +471,162 @@ export class Bucket {
    }
  }
  // ==========================================
  // Memory-Efficient Listing Methods (Phase 1)
  // ==========================================
  /**
   * List all objects with a given prefix using async generator (memory-efficient streaming)
   * @param prefix - Optional prefix to filter objects (default: '' for all objects)
   * @yields Object keys one at a time
   * @example
   * ```ts
   * for await (const key of bucket.listAllObjects('npm/')) {
   *   console.log(key);
   *   if (shouldStop) break; // Early exit supported
   * }
   * ```
   */
  public async *listAllObjects(prefix: string = ''): AsyncIterableIterator<string> {
    let continuationToken: string | undefined;
    do {
      const command = new plugins.s3.ListObjectsV2Command({
        Bucket: this.name,
        Prefix: prefix,
        ContinuationToken: continuationToken,
      });
      const response = await this.smartbucketRef.storageClient.send(command);
      for (const obj of response.Contents || []) {
        if (obj.Key) yield obj.Key;
      }
      continuationToken = response.NextContinuationToken;
    } while (continuationToken);
  }
  /**
   * List all objects as an RxJS Observable (for complex reactive pipelines)
   * @param prefix - Optional prefix to filter objects (default: '' for all objects)
   * @returns Observable that emits object keys
   * @example
   * ```ts
   * bucket.listAllObjectsObservable('npm/')
   *   .pipe(
   *     filter(key => key.endsWith('.json')),
   *     take(100)
   *   )
   *   .subscribe(key => console.log(key));
   * ```
   */
  public listAllObjectsObservable(prefix: string = ''): plugins.smartrx.rxjs.Observable<string> {
    return new plugins.smartrx.rxjs.Observable<string>((subscriber) => {
      const fetchPage = async (token?: string) => {
        try {
          const command = new plugins.s3.ListObjectsV2Command({
            Bucket: this.name,
            Prefix: prefix,
            ContinuationToken: token,
          });
          const response = await this.smartbucketRef.storageClient.send(command);
          for (const obj of response.Contents || []) {
            if (obj.Key) subscriber.next(obj.Key);
          }
          if (response.NextContinuationToken) {
            await fetchPage(response.NextContinuationToken);
          } else {
            subscriber.complete();
          }
        } catch (error) {
          subscriber.error(error);
        }
      };
      fetchPage();
    });
  }
  /**
   * Create a cursor for manual pagination control
   * @param prefix - Optional prefix to filter objects (default: '' for all objects)
   * @param options - Cursor options (pageSize, etc.)
   * @returns ListCursor instance
   * @example
   * ```ts
   * const cursor = bucket.createCursor('npm/', { pageSize: 500 });
   * while (cursor.hasMore()) {
   *   const { keys, done } = await cursor.next();
   *   console.log(`Processing ${keys.length} keys...`);
   * }
   * ```
   */
  public createCursor(prefix: string = '', options?: IListCursorOptions): ListCursor {
    return new ListCursor(this, prefix, options);
  }
  /**
   * Create a watcher for monitoring bucket changes (add/modify/delete)
   * @param options - Watcher options (prefix, pollIntervalMs, etc.)
   * @returns BucketWatcher instance
   * @example
   * ```ts
   * const watcher = bucket.createWatcher({ prefix: 'uploads/', pollIntervalMs: 3000 });
   * watcher.changeSubject.subscribe((change) => console.log('Change:', change));
   * await watcher.start();
   * // ... later
   * await watcher.stop();
   * ```
   */
  public createWatcher(options?: interfaces.IBucketWatcherOptions): BucketWatcher {
    return new BucketWatcher(this, options);
  }
  // ==========================================
  // High-Level Listing Helpers (Phase 2)
  // ==========================================
  /**
   * Find objects matching a glob pattern (memory-efficient)
   * @param pattern - Glob pattern (e.g., "**\/*.json", "npm/packages/*\/index.json")
   * @yields Matching object keys
   * @example
   * ```ts
   * for await (const key of bucket.findByGlob('npm/packages/*\/index.json')) {
   *   console.log('Found package index:', key);
   * }
   * ```
   */
  public async *findByGlob(pattern: string): AsyncIterableIterator<string> {
    const matcher = new plugins.Minimatch(pattern);
    for await (const key of this.listAllObjects('')) {
      if (matcher.match(key)) yield key;
    }
  }
  /**
   * List all objects and collect into an array (convenience method)
   * WARNING: Loads entire result set into memory. Use listAllObjects() generator for large buckets.
   * @param prefix - Optional prefix to filter objects (default: '' for all objects)
   * @returns Array of all object keys
   * @example
   * ```ts
   * const allKeys = await bucket.listAllObjectsArray('npm/');
   * console.log(`Found ${allKeys.length} objects`);
   * ```
   */
  public async listAllObjectsArray(prefix: string = ''): Promise<string[]> {
    const keys: string[] = [];
    for await (const key of this.listAllObjects(prefix)) {
      keys.push(key);
    }
    return keys;
  }
  public async cleanAllContents(): Promise<void> {
    try {
      // Define the command type explicitly
@@ -488,7 +646,7 @@ export class Bucket {
        // Explicitly type the response
        const response: plugins.s3.ListObjectsV2Output =
-          await this.smartbucketRef.s3Client.send(listCommand);
+          await this.smartbucketRef.storageClient.send(listCommand);
        console.log(`Cleaning contents of bucket '${this.name}': Now deleting ${response.Contents?.length} items...`);
@@ -502,7 +660,7 @@ export class Bucket {
            },
          });
-          await this.smartbucketRef.s3Client.send(deleteCommand);
+          await this.smartbucketRef.storageClient.send(deleteCommand);
        }
        // Update continuation token and truncation status
--- a/ts/classes.directory.ts
+++ b/ts/classes.directory.ts
@@ -120,19 +120,44 @@ export class Directory {
    return directories.some(dir => dir.name === dirNameArg);
  }
  /**
   * Collects all ListObjectsV2 pages for a prefix.
   */
  private async listObjectsV2AllPages(prefix: string, delimiter?: string) {
    const allContents: plugins.s3._Object[] = [];
    const allCommonPrefixes: plugins.s3.CommonPrefix[] = [];
    let continuationToken: string | undefined;
    do {
      const command = new plugins.s3.ListObjectsV2Command({
        Bucket: this.bucketRef.name,
        Prefix: prefix,
        Delimiter: delimiter,
        ContinuationToken: continuationToken,
      });
      const response = await this.bucketRef.smartbucketRef.storageClient.send(command);
      if (response.Contents) {
        allContents.push(...response.Contents);
      }
      if (response.CommonPrefixes) {
        allCommonPrefixes.push(...response.CommonPrefixes);
      }
      continuationToken = response.IsTruncated ? response.NextContinuationToken : undefined;
    } while (continuationToken);
    return { contents: allContents, commonPrefixes: allCommonPrefixes };
  }
  /**
   * lists all files
   */
  public async listFiles(): Promise<File[]> {
-    const command = new plugins.s3.ListObjectsV2Command({
+    const { contents } = await this.listObjectsV2AllPages(this.getBasePath(), '/');
      Bucket: this.bucketRef.name,
      Prefix: this.getBasePath(),
      Delimiter: '/',
    });
    const response = await this.bucketRef.smartbucketRef.s3Client.send(command);
    const fileArray: File[] = [];
-    response.Contents?.forEach((item) => {
+    contents.forEach((item) => {
      if (item.Key && !item.Key.endsWith('/')) {
        const subtractedPath = item.Key.replace(this.getBasePath(), '');
        if (!subtractedPath.includes('/')) {
@@ -154,16 +179,11 @@ export class Directory {
   */
  public async listDirectories(): Promise<Directory[]> {
    try {
-      const command = new plugins.s3.ListObjectsV2Command({
+      const { commonPrefixes } = await this.listObjectsV2AllPages(this.getBasePath(), '/');
        Bucket: this.bucketRef.name,
        Prefix: this.getBasePath(),
        Delimiter: '/',
      });
      const response = await this.bucketRef.smartbucketRef.s3Client.send(command);
      const directoryArray: Directory[] = [];
-      if (response.CommonPrefixes) {
+      if (commonPrefixes) {
-        response.CommonPrefixes.forEach((item) => {
+        commonPrefixes.forEach((item) => {
          if (item.Prefix) {
            const subtractedPath = item.Prefix.replace(this.getBasePath(), '');
            if (subtractedPath.endsWith('/')) {
@@ -193,7 +213,7 @@ export class Directory {
      Prefix: this.getBasePath(),
      Delimiter: '/',
    });
-    const response = await this.bucketRef.smartbucketRef.s3Client.send(command);
+    const response = await this.bucketRef.smartbucketRef.storageClient.send(command);
    return response.Contents;
  }
@@ -202,12 +222,12 @@ export class Directory {
   */
  public async getSubDirectoryByName(dirNameArg: string, optionsArg: {
    /**
-     * in s3 a directory does not exist if it is empty
+     * in object storage a directory does not exist if it is empty
     * this option returns a directory even if it is empty
     */
    getEmptyDirectory?: boolean;
    /**
-     * in s3 a directory does not exist if it is empty
+     * in object storage a directory does not exist if it is empty
     * this option creates a directory even if it is empty using a initializer file
     */
    createWithInitializerFile?: boolean;
@@ -235,7 +255,7 @@ export class Directory {
        return returnDirectory;
      }
      if (optionsArg.getEmptyDirectory || optionsArg.createWithInitializerFile) {
-        returnDirectory = new Directory(this.bucketRef, this, dirNameToSearch);
+        returnDirectory = new Directory(this.bucketRef, directoryArg, dirNameToSearch);
      }
      if (isFinalDirectory && optionsArg.createWithInitializerFile) {
        returnDirectory?.createEmptyFile('00init.txt');
--- a/ts/classes.file.ts
+++ b/ts/classes.file.ts
@@ -12,7 +12,7 @@ export class File {
  /**
   * creates a file in draft mode
-   * you need to call .save() to store it in s3
+   * you need to call .save() to store it in object storage
   * @param optionsArg
   */
  public static async create(optionsArg: {
--- a/ts/classes.listcursor.ts
+++ b/ts/classes.listcursor.ts
@@ -0,0 +1,89 @@
 // classes.listcursor.ts
 import * as plugins from './plugins.js';
 import type { Bucket } from './classes.bucket.js';
 export interface IListCursorOptions {
  pageSize?: number;
 }
 export interface IListCursorResult {
  keys: string[];
  done: boolean;
 }
 /**
 * ListCursor provides explicit pagination control for listing objects in a bucket.
 * Useful for UI pagination, resumable operations, and manual batch processing.
 */
 export class ListCursor {
  private continuationToken?: string;
  private exhausted = false;
  private pageSize: number;
  constructor(
    private bucket: Bucket,
    private prefix: string,
    options: IListCursorOptions = {}
  ) {
    this.pageSize = options.pageSize || 1000;
  }
  /**
   * Fetch the next page of object keys
   * @returns Object with keys array and done flag
   */
  public async next(): Promise<IListCursorResult> {
    if (this.exhausted) {
      return { keys: [], done: true };
    }
    const command = new plugins.s3.ListObjectsV2Command({
      Bucket: this.bucket.name,
      Prefix: this.prefix,
      MaxKeys: this.pageSize,
      ContinuationToken: this.continuationToken,
    });
    const response = await this.bucket.smartbucketRef.storageClient.send(command);
    const keys = (response.Contents || [])
      .map((obj) => obj.Key)
      .filter((key): key is string => !!key);
    this.continuationToken = response.NextContinuationToken;
    this.exhausted = !this.continuationToken;
    return { keys, done: this.exhausted };
  }
  /**
   * Check if there are more pages to fetch
   */
  public hasMore(): boolean {
    return !this.exhausted;
  }
  /**
   * Reset the cursor to start from the beginning
   */
  public reset(): void {
    this.continuationToken = undefined;
    this.exhausted = false;
  }
  /**
   * Get the current continuation token (for saving/restoring state)
   */
  public getToken(): string | undefined {
    return this.continuationToken;
  }
  /**
   * Set the continuation token (for resuming from a saved state)
   */
  public setToken(token: string | undefined): void {
    this.continuationToken = token;
    this.exhausted = !token;
  }
 }
--- a/ts/classes.metadata.ts
+++ b/ts/classes.metadata.ts
@@ -4,11 +4,23 @@ import { File } from './classes.file.js';
 export class MetaData {
  public static async hasMetaData(optionsArg: { file: File }) {
-    // lets find the existing metadata file
+    // try finding the existing metadata file; return false if it doesn't exist
-    const existingFile = await optionsArg.file.parentDirectoryRef.getFile({
+    try {
-      path: optionsArg.file.name + '.metadata',
+      const existingFile = await optionsArg.file.parentDirectoryRef.getFile({
-    });
+        path: optionsArg.file.name + '.metadata',
-    return !!existingFile;
+      });
      return !!existingFile;
    } catch (error: any) {
      const message = error?.message || '';
      const isNotFound =
        message.includes('File not found') ||
        error?.name === 'NotFound' ||
        error?.$metadata?.httpStatusCode === 404;
      if (isNotFound) {
        return false;
      }
      throw error;
    }
  }
  // static
--- a/ts/classes.smartbucket.ts
+++ b/ts/classes.smartbucket.ts
@@ -2,26 +2,28 @@
 import * as plugins from './plugins.js';
 import { Bucket } from './classes.bucket.js';
-import { normalizeS3Descriptor } from './helpers.js';
+import { normalizeStorageDescriptor } from './helpers.js';
 export class SmartBucket {
-  public config: plugins.tsclass.storage.IS3Descriptor;
+  public config: plugins.tsclass.storage.IStorageDescriptor;
-  public s3Client: plugins.s3.S3Client;
+  public storageClient: plugins.s3.S3Client;
  /** @deprecated Use storageClient instead */
  public get s3Client(): plugins.s3.S3Client {
    return this.storageClient;
  }
  /**
   * the constructor of SmartBucket
   */
-  /**
+  constructor(configArg: plugins.tsclass.storage.IStorageDescriptor) {
   * the constructor of SmartBucket
   */
  constructor(configArg: plugins.tsclass.storage.IS3Descriptor) {
    this.config = configArg;
    // Use the normalizer to handle various endpoint formats
-    const { normalized } = normalizeS3Descriptor(configArg);
+    const { normalized } = normalizeStorageDescriptor(configArg);
-    this.s3Client = new plugins.s3.S3Client({
+    this.storageClient = new plugins.s3.S3Client({
      endpoint: normalized.endpointUrl,
      region: normalized.region,
      credentials: normalized.credentials,
@@ -47,7 +49,7 @@ export class SmartBucket {
   */
  public async bucketExists(bucketNameArg: string): Promise<boolean> {
    const command = new plugins.s3.ListBucketsCommand({});
-    const buckets = await this.s3Client.send(command);
+    const buckets = await this.storageClient.send(command);
    return buckets.Buckets?.some(bucket => bucket.Name === bucketNameArg) ?? false;
  }
 }
--- a/ts/classes.watcher.ts
+++ b/ts/classes.watcher.ts
@@ -0,0 +1,289 @@
 // classes.watcher.ts
 import * as plugins from './plugins.js';
 import * as interfaces from './interfaces.js';
 import type { Bucket } from './classes.bucket.js';
 import { EventEmitter } from 'node:events';
 /**
 * BucketWatcher monitors a storage bucket for changes (add/modify/delete)
 * using a polling-based approach. Designed to follow the SmartdataDbWatcher pattern.
 *
 * @example
 * ```typescript
 * const watcher = bucket.createWatcher({ prefix: 'uploads/', pollIntervalMs: 3000 });
 *
 * // RxJS Observable pattern
 * watcher.changeSubject.subscribe((change) => {
 *   console.log('Change:', change);
 * });
 *
 * // EventEmitter pattern
 * watcher.on('change', (change) => console.log(change));
 * watcher.on('error', (err) => console.error(err));
 *
 * await watcher.start();
 * await watcher.readyDeferred.promise; // Wait for initial state
 *
 * // Later...
 * await watcher.stop();
 * ```
 */
 export class BucketWatcher extends EventEmitter {
  /** Deferred that resolves when initial state is built and watcher is ready */
  public readyDeferred = plugins.smartpromise.defer();
  /** Observable for receiving change events (supports RxJS operators) */
  public changeSubject: plugins.smartrx.rxjs.Observable<interfaces.IStorageChangeEvent | interfaces.IStorageChangeEvent[]>;
  // Internal subjects and state
  private rawSubject: plugins.smartrx.rxjs.Subject<interfaces.IStorageChangeEvent>;
  private previousState: Map<string, interfaces.IStorageObjectState>;
  private pollIntervalId: ReturnType<typeof setInterval> | null = null;
  private isPolling = false;
  private isStopped = false;
  // Configuration
  private readonly bucketRef: Bucket;
  private readonly prefix: string;
  private readonly pollIntervalMs: number;
  private readonly bufferTimeMs?: number;
  private readonly includeInitial: boolean;
  private readonly pageSize: number;
  constructor(bucketRef: Bucket, options: interfaces.IBucketWatcherOptions = {}) {
    super();
    this.bucketRef = bucketRef;
    this.prefix = options.prefix ?? '';
    this.pollIntervalMs = options.pollIntervalMs ?? 5000;
    this.bufferTimeMs = options.bufferTimeMs;
    this.includeInitial = options.includeInitial ?? false;
    this.pageSize = options.pageSize ?? 1000;
    // Initialize state tracking
    this.previousState = new Map();
    // Initialize raw subject for emitting changes
    this.rawSubject = new plugins.smartrx.rxjs.Subject<interfaces.IStorageChangeEvent>();
    // Configure the public observable with optional buffering
    if (this.bufferTimeMs && this.bufferTimeMs > 0) {
      this.changeSubject = this.rawSubject.pipe(
        plugins.smartrx.rxjs.ops.bufferTime(this.bufferTimeMs),
        plugins.smartrx.rxjs.ops.filter((events: interfaces.IStorageChangeEvent[]) => events.length > 0)
      );
    } else {
      this.changeSubject = this.rawSubject.asObservable();
    }
  }
  /**
   * Start watching the bucket for changes
   */
  public async start(): Promise<void> {
    if (this.pollIntervalId !== null) {
      console.log('BucketWatcher is already running');
      return;
    }
    this.isStopped = false;
    // Build initial state
    await this.buildInitialState();
    // Emit initial state as 'add' events if configured
    if (this.includeInitial) {
      for (const state of this.previousState.values()) {
        this.emitChange({
          type: 'add',
          key: state.key,
          size: state.size,
          etag: state.etag,
          lastModified: state.lastModified,
          bucket: this.bucketRef.name,
        });
      }
    }
    // Mark as ready
    this.readyDeferred.resolve();
    // Start polling loop
    this.pollIntervalId = setInterval(() => {
      this.poll().catch((err) => {
        this.emit('error', err);
      });
    }, this.pollIntervalMs);
  }
  /**
   * Stop watching the bucket
   */
  public async stop(): Promise<void> {
    this.isStopped = true;
    if (this.pollIntervalId !== null) {
      clearInterval(this.pollIntervalId);
      this.pollIntervalId = null;
    }
    // Wait for any in-progress poll to complete
    while (this.isPolling) {
      await new Promise<void>((resolve) => setTimeout(resolve, 50));
    }
    this.rawSubject.complete();
  }
  /**
   * Alias for stop() - for consistency with other APIs
   */
  public async close(): Promise<void> {
    return this.stop();
  }
  /**
   * Build the initial state by listing all objects with metadata
   */
  private async buildInitialState(): Promise<void> {
    this.previousState.clear();
    for await (const obj of this.listObjectsWithMetadata()) {
      if (obj.Key) {
        this.previousState.set(obj.Key, {
          key: obj.Key,
          etag: obj.ETag ?? '',
          size: obj.Size ?? 0,
          lastModified: obj.LastModified ?? new Date(0),
        });
      }
    }
  }
  /**
   * Poll for changes by comparing current state against previous state
   */
  private async poll(): Promise<void> {
    // Guard against overlapping polls
    if (this.isPolling || this.isStopped) {
      return;
    }
    this.isPolling = true;
    try {
      // Build current state
      const currentState = new Map<string, interfaces.IStorageObjectState>();
      for await (const obj of this.listObjectsWithMetadata()) {
        if (this.isStopped) {
          break;
        }
        if (obj.Key) {
          currentState.set(obj.Key, {
            key: obj.Key,
            etag: obj.ETag ?? '',
            size: obj.Size ?? 0,
            lastModified: obj.LastModified ?? new Date(0),
          });
        }
      }
      if (!this.isStopped) {
        this.detectChanges(currentState);
        this.previousState = currentState;
      }
    } catch (err) {
      this.emit('error', err);
    } finally {
      this.isPolling = false;
    }
  }
  /**
   * Detect changes between current and previous state
   */
  private detectChanges(currentState: Map<string, interfaces.IStorageObjectState>): void {
    // Detect added and modified objects
    for (const [key, current] of currentState) {
      const previous = this.previousState.get(key);
      if (!previous) {
        // New object - emit 'add' event
        this.emitChange({
          type: 'add',
          key: current.key,
          size: current.size,
          etag: current.etag,
          lastModified: current.lastModified,
          bucket: this.bucketRef.name,
        });
      } else if (
        previous.etag !== current.etag ||
        previous.size !== current.size ||
        previous.lastModified.getTime() !== current.lastModified.getTime()
      ) {
        // Object modified - emit 'modify' event
        this.emitChange({
          type: 'modify',
          key: current.key,
          size: current.size,
          etag: current.etag,
          lastModified: current.lastModified,
          bucket: this.bucketRef.name,
        });
      }
    }
    // Detect deleted objects
    for (const [key, previous] of this.previousState) {
      if (!currentState.has(key)) {
        // Object deleted - emit 'delete' event
        this.emitChange({
          type: 'delete',
          key: previous.key,
          bucket: this.bucketRef.name,
        });
      }
    }
  }
  /**
   * Emit a change event via both RxJS Subject and EventEmitter
   */
  private emitChange(event: interfaces.IStorageChangeEvent): void {
    this.rawSubject.next(event);
    this.emit('change', event);
  }
  /**
   * List objects with full metadata (ETag, Size, LastModified)
   * This is a private method that yields full _Object data, not just keys
   */
  private async *listObjectsWithMetadata(): AsyncIterableIterator<plugins.s3._Object> {
    let continuationToken: string | undefined;
    do {
      if (this.isStopped) {
        return;
      }
      const command = new plugins.s3.ListObjectsV2Command({
        Bucket: this.bucketRef.name,
        Prefix: this.prefix,
        MaxKeys: this.pageSize,
        ContinuationToken: continuationToken,
      });
      const response = await this.bucketRef.smartbucketRef.storageClient.send(command);
      for (const obj of response.Contents || []) {
        yield obj;
      }
      continuationToken = response.NextContinuationToken;
    } while (continuationToken);
  }
 }
--- a/ts/helpers.ts
+++ b/ts/helpers.ts
@@ -21,13 +21,13 @@ export const reducePathDescriptorToPath = async (pathDescriptorArg: interfaces.I
  return returnPath;
 }
-// S3 Descriptor Normalization
+// Storage Descriptor Normalization
-export interface IS3Warning {
+export interface IStorageWarning {
  code: string;
  message: string;
 }
-export interface INormalizedS3Config {
+export interface INormalizedStorageConfig {
  endpointUrl: string;
  host: string;
  protocol: 'http' | 'https';
@@ -40,7 +40,7 @@ export interface INormalizedS3Config {
  forcePathStyle: boolean;
 }
-function coerceBooleanMaybe(value: unknown): { value: boolean | undefined; warning?: IS3Warning } {
+function coerceBooleanMaybe(value: unknown): { value: boolean | undefined; warning?: IStorageWarning } {
  if (typeof value === 'boolean') return { value };
  if (typeof value === 'string') {
    const v = value.trim().toLowerCase();
@@ -66,7 +66,7 @@ function coerceBooleanMaybe(value: unknown): { value: boolean | undefined; warni
  return { value: undefined };
 }
-function coercePortMaybe(port: unknown): { value: number | undefined; warning?: IS3Warning } {
+function coercePortMaybe(port: unknown): { value: number | undefined; warning?: IStorageWarning } {
  if (port === undefined || port === null || port === '') return { value: undefined };
  const n = typeof port === 'number' ? port : Number(String(port).trim());
  if (!Number.isFinite(n) || !Number.isInteger(n) || n <= 0 || n > 65535) {
@@ -81,8 +81,8 @@ function coercePortMaybe(port: unknown): { value: number | undefined; warning?:
  return { value: n };
 }
-function sanitizeEndpointString(raw: unknown): { value: string; warnings: IS3Warning[] } {
+function sanitizeEndpointString(raw: unknown): { value: string; warnings: IStorageWarning[] } {
-  const warnings: IS3Warning[] = [];
+  const warnings: IStorageWarning[] = [];
  let s = String(raw ?? '').trim();
  if (s !== String(raw ?? '')) {
    warnings.push({ 
@@ -138,17 +138,17 @@ function parseEndpointHostPort(
  return { hadScheme, host, port, extras };
 }
-export function normalizeS3Descriptor(
+export function normalizeStorageDescriptor(
-  input: plugins.tsclass.storage.IS3Descriptor,
+  input: plugins.tsclass.storage.IStorageDescriptor,
  logger?: { warn: (msg: string) => void }
-): { normalized: INormalizedS3Config; warnings: IS3Warning[] } {
+): { normalized: INormalizedStorageConfig; warnings: IStorageWarning[] } {
-  const warnings: IS3Warning[] = [];
+  const warnings: IStorageWarning[] = [];
-  const logWarn = (w: IS3Warning) => { 
+  const logWarn = (w: IStorageWarning) => { 
    warnings.push(w); 
    if (logger) {
-      logger.warn(`[SmartBucket S3] ${w.code}: ${w.message}`);
+      logger.warn(`[SmartBucket] ${w.code}: ${w.message}`);
    } else {
-      console.warn(`[SmartBucket S3] ${w.code}: ${w.message}`);
+      console.warn(`[SmartBucket] ${w.code}: ${w.message}`);
    }
  };
@@ -163,7 +163,7 @@ export function normalizeS3Descriptor(
  endpointSanWarnings.forEach(logWarn);
  if (!endpointStr) {
-    throw new Error('S3 endpoint is required (got empty string). Provide hostname or URL.');
+    throw new Error('Storage endpoint is required (got empty string). Provide hostname or URL.');
  }
  // Provisional protocol selection for parsing host:port forms
--- a/ts/index.ts
+++ b/ts/index.ts
@@ -2,3 +2,8 @@ export * from './classes.smartbucket.js';
 export * from './classes.bucket.js';
 export * from './classes.directory.js';
 export * from './classes.file.js';
 export * from './classes.listcursor.js';
 export * from './classes.metadata.js';
 export * from './classes.trash.js';
 export * from './classes.watcher.js';
 export * from './interfaces.js';
--- a/ts/interfaces.ts
+++ b/ts/interfaces.ts
@@ -4,3 +4,64 @@ export interface IPathDecriptor {
  path?: string;
  directory?: Directory;
 }
 // ================================
 // Bucket Watcher Interfaces
 // ================================
 /**
 * Internal state tracking for a storage object
 */
 export interface IStorageObjectState {
  key: string;
  etag: string;
  size: number;
  lastModified: Date;
 }
 /**
 * Change event emitted by BucketWatcher
 */
 export interface IStorageChangeEvent {
  type: 'add' | 'modify' | 'delete';
  key: string;
  size?: number;
  etag?: string;
  lastModified?: Date;
  bucket: string;
 }
 /**
 * Watcher mode - 'poll' is the default, 'websocket' reserved for future implementation
 */
 export type TBucketWatcherMode = 'poll' | 'websocket';
 /**
 * Options for creating a BucketWatcher
 */
 export interface IBucketWatcherOptions {
  /** Watcher mode: 'poll' (default) or 'websocket' (future) */
  mode?: TBucketWatcherMode;
  /** Prefix to filter objects (default: '' for all objects) */
  prefix?: string;
  /** Polling interval in milliseconds (default: 5000, poll mode only) */
  pollIntervalMs?: number;
  /** Optional RxJS buffering time in milliseconds */
  bufferTimeMs?: number;
  /** Emit initial state as 'add' events (default: false) */
  includeInitial?: boolean;
  /** Page size for listing operations (default: 1000) */
  pageSize?: number;
  // Future websocket options will be added here
  // websocketUrl?: string;
 }
 // ================================
 // Deprecated aliases
 // ================================
 /** @deprecated Use IStorageObjectState instead */
 export type IS3ObjectState = IStorageObjectState;
 /** @deprecated Use IStorageChangeEvent instead */
 export type IS3ChangeEvent = IStorageChangeEvent;
--- a/ts/plugins.ts
+++ b/ts/plugins.ts
@@ -1,8 +1,8 @@
 // plugins.ts
 // node native
-import * as path from 'path';
+import * as path from 'node:path';
-import * as stream from 'stream';
+import * as stream from 'node:stream';
 export { path, stream };
@@ -26,7 +26,9 @@ export {
 // third party scope
 import * as s3 from '@aws-sdk/client-s3';
 import { Minimatch } from 'minimatch';
 export {
  s3,
  Minimatch,
 }
Author	SHA1	Message	Date
Juergen Kunz	b905af4132	v4.5.1	2026-03-14 22:42:29 +00:00
Juergen Kunz	ec9cfab9c9	fix(readme): refresh documentation wording and simplify README formatting	2026-03-14 22:42:29 +00:00
Juergen Kunz	fac59e24d7	v4.5.0	2026-03-14 19:24:36 +00:00
Juergen Kunz	18bdb5c7c2	feat(storage): generalize S3 client and watcher interfaces to storage-oriented naming with backward compatibility	2026-03-14 19:24:36 +00:00
Juergen Kunz	7959fa6296	v4.4.1	2026-01-25 18:10:51 +00:00
Juergen Kunz	2640fa07c4	v4.4.0	2026-01-25 18:09:38 +00:00
Juergen Kunz	7bb994e1cb	feat(watcher): add polling-based BucketWatcher to detect add/modify/delete events and expose RxJS Observable and EventEmitter APIs	2026-01-25 18:09:38 +00:00
Juergen Kunz	575cff4d09	v4.3.1	2026-01-24 09:55:44 +00:00
Juergen Kunz	6760fd480d	fix(bucket): propagate S3 client errors instead of silently logging them; update build script, bump dev/dependencies, and refresh npmextra configuration	2026-01-24 09:55:44 +00:00
Juergen Kunz	bd73004bd6	v4.3.0	2025-11-20 15:14:11 +00:00
Juergen Kunz	65c7bcf12c	feat(listing): Add memory-efficient listing APIs: async generator, RxJS observable, and cursor pagination; export ListCursor and Minimatch; add minimatch dependency; bump to 4.2.0	2025-11-20 15:14:11 +00:00
Juergen Kunz	dd6efa4908	v4.1.0	2025-11-20 13:58:02 +00:00
Juergen Kunz	1f4b7319d3	feat(core): Add S3 endpoint normalization, directory pagination, improved metadata checks, trash support, and related tests	2025-11-20 13:58:02 +00:00
Juergen Kunz	b8e5d9a222	v4.0.1	2025-11-20 13:38:53 +00:00
Juergen Kunz	429375a643	fix(plugins): Use explicit node: imports for native path and stream modules in ts/plugins.ts	2025-11-20 13:38:53 +00:00