v4.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
v4.1.0
2025-11-20 15:14:11 +00:00 · 2025-11-20 15:14:11 +00:00 · 2025-11-20 13:58:02 +00:00 · 2025-11-20 13:58:02 +00:00 · 2025-11-20 13:38:53 +00:00 · 2025-11-20 13:38:53 +00:00
31 changed files with 18330 additions and 3282 deletions
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -1,140 +0,0 @@
-# gitzone ci_default
-image: registry.gitlab.com/hosttoday/ht-docker-node:npmci
-
-cache:
-  paths:
-    - .npmci_cache/
-  key: '$CI_BUILD_STAGE'
-
-stages:
-  - security
-  - test
-  - release
-  - metadata
-
-before_script:
-  - npm install -g @shipzone/npmci
-
-# ====================
-# security stage
-# ====================
-mirror:
-  stage: security
-  script:
-    - npmci git mirror
-  only:
-    - tags
-  tags:
-    - lossless
-    - docker
-    - notpriv
-
-auditProductionDependencies:
-  image: registry.gitlab.com/hosttoday/ht-docker-node:npmci
-  stage: security
-  script:
-    - npmci npm prepare
-    - npmci command npm install --production --ignore-scripts
-    - npmci command npm config set registry https://registry.npmjs.org
-    - npmci command npm audit --audit-level=high --only=prod --production
-  tags:
-    - docker
-  allow_failure: true
-
-auditDevDependencies:
-  image: registry.gitlab.com/hosttoday/ht-docker-node:npmci
-  stage: security
-  script:
-    - npmci npm prepare
-    - npmci command npm install --ignore-scripts
-    - npmci command npm config set registry https://registry.npmjs.org
-    - npmci command npm audit --audit-level=high --only=dev
-  tags:
-    - docker
-  allow_failure: true
-
-# ====================
-# test stage
-# ====================
-
-testStable:
-  stage: test
-  script:
-    - npmci npm prepare
-    - npmci node install stable
-    - npmci npm install
-    - npmci npm test
-  coverage: /\d+.?\d+?\%\s*coverage/
-  tags:
-    - docker
-
-testBuild:
-  stage: test
-  script:
-    - npmci npm prepare
-    - npmci node install stable
-    - npmci npm install
-    - npmci command npm run build
-  coverage: /\d+.?\d+?\%\s*coverage/
-  tags:
-    - docker
-
-release:
-  stage: release
-  script:
-    - npmci node install stable
-    - npmci npm publish
-  only:
-    - tags
-  tags:
-    - lossless
-    - docker
-    - notpriv
-
-# ====================
-# metadata stage
-# ====================
-codequality:
-  stage: metadata
-  allow_failure: true
-  only:
-    - tags
-  script:
-    - npmci command npm install -g typescript
-    - npmci npm prepare
-    - npmci npm install
-  tags:
-    - lossless
-    - docker
-    - priv
-
-trigger:
-  stage: metadata
-  script:
-    - npmci trigger
-  only:
-    - tags
-  tags:
-    - lossless
-    - docker
-    - notpriv
-
-pages:
-  stage: metadata
-  script:
-    - npmci node install lts
-    - npmci command npm install -g @git.zone/tsdoc
-    - npmci npm prepare
-    - npmci npm install
-    - npmci command tsdoc
-  tags:
-    - lossless
-    - docker
-    - notpriv
-  only:
-    - tags
-  artifacts:
-    expire_in: 1 week
-    paths:
-      - public
-  allow_failure: true
--- a/changelog.md
+++ b/changelog.md
@@ -0,0 +1,351 @@
+# Changelog
+
+## 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
+
+- Breaking: Core API methods are strict by default and now throw errors instead of returning null when targets are missing or already exist (e.g. getBucketByName, getFile, getSubDirectoryByName, fastPut, fastPutStream).
+- Removed *Strict variants: fastPutStrict, getBucketByNameStrict, getFileStrict, getSubDirectoryByNameStrict — use the base methods which are now strict.
+- Added explicit existence checks: bucketExists (SmartBucket), fileExists (Directory/fileExists), directoryExists (Directory.directoryExists), and fastExists (Bucket.fastExists) to allow non-throwing checks before operations.
+- Return type updates: fastPut now returns Promise<File> (no null), getBucketByName/getFile/getSubDirectoryByName now return the respective objects or throw.
+- Improved error messages to guide callers (e.g. suggest setting overwrite:true on fastPut when object exists).
+- Updated README, changelog and tests to reflect the new strict semantics and usage patterns.
+- Developer/runtime dependency bumps: @git.zone/tsbuild, @git.zone/tsrun, @git.zone/tstest, @aws-sdk/client-s3, @push.rocks/smartstring, @tsclass/tsclass (version bumps recorded in package.json).
+- Major version bump to 4.0.0 to reflect breaking API changes.
+
+## 2025-11-20 - 4.0.0 - BREAKING: Strict by default + exists methods
+Complete API overhaul: all methods throw by default, removed all *Strict variants, added dedicated exists methods
+
+**Breaking Changes:**
+
+**Putters (Write Operations):**
+- `fastPut`: Return type `Promise<File | null>` → `Promise<File>`, throws when file exists and overwrite is false
+- `fastPutStream`: Now throws when file exists and overwrite is false (previously returned silently)
+- `fastPutStrict`: **Removed** - use `fastPut` directly
+
+**Getters (Read Operations):**
+- `getBucketByName`: Return type `Promise<Bucket | null>` → `Promise<Bucket>`, throws when bucket not found
+- `getBucketByNameStrict`: **Removed** - use `getBucketByName` directly
+- `getFile`: Return type `Promise<File | null>` → `Promise<File>`, throws when file not found
+- `getFileStrict`: **Removed** - use `getFile` directly
+- `getSubDirectoryByName`: Return type `Promise<Directory | null>` → `Promise<Directory>`, throws when directory not found
+- `getSubDirectoryByNameStrict`: **Removed** - use `getSubDirectoryByName` directly
+
+**New Methods (Existence Checks):**
+- `bucket.fastExists({ path })` - ✅ Already existed
+- `directory.fileExists({ path })` - **NEW** - Check if file exists
+- `directory.directoryExists(name)` - **NEW** - Check if subdirectory exists
+- `smartBucket.bucketExists(name)` - **NEW** - Check if bucket exists
+
+**Benefits:**
+- ✅ **Simpler API**: Removed 4 redundant *Strict methods
+- ✅ **Type-safe**: No nullable returns - `Promise<T>` not `Promise<T | null>`
+- ✅ **Fail-fast**: Errors throw immediately with precise stack traces
+- ✅ **Consistent**: All methods behave the same way
+- ✅ **Explicit**: Use exists() to check, then get() to retrieve
+- ✅ **Better debugging**: Error location is always precise
+
+**Migration Guide:**
+
+```typescript
+// ============================================
+// Pattern 1: Check then Get (Recommended)
+// ============================================
+
+// Before (v3.x):
+const bucket = await smartBucket.getBucketByName('my-bucket');
+if (bucket) {
+  // use bucket
+}
+
+// After (v4.0):
+if (await smartBucket.bucketExists('my-bucket')) {
+  const bucket = await smartBucket.getBucketByName('my-bucket'); // guaranteed to exist
+  // use bucket
+}
+
+// ============================================
+// Pattern 2: Try/Catch
+// ============================================
+
+// Before (v3.x):
+const file = await directory.getFile({ path: 'file.txt' });
+if (!file) {
+  // Handle not found
+}
+
+// After (v4.0):
+try {
+  const file = await directory.getFile({ path: 'file.txt' });
+  // use file
+} catch (error) {
+  // Handle not found
+}
+
+// ============================================
+// Pattern 3: Remove *Strict calls
+// ============================================
+
+// Before (v3.x):
+const file = await directory.getFileStrict({ path: 'file.txt' });
+
+// After (v4.0):
+const file = await directory.getFile({ path: 'file.txt' }); // already strict
+
+// ============================================
+// Pattern 4: Write Operations
+// ============================================
+
+// Before (v3.x):
+const file = await bucket.fastPutStrict({ path: 'file.txt', contents: 'data' });
+
+// After (v4.0):
+const file = await bucket.fastPut({ path: 'file.txt', contents: 'data' }); // already strict
+```
+
+## 2025-08-18 - 3.3.10 - fix(helpers)
+Normalize and robustly parse S3 endpoint configuration; use normalized descriptor in SmartBucket and update dev tooling
+
+- Add normalizeS3Descriptor to ts/helpers.ts: robust endpoint parsing, coercion of useSsl/port, sanitization, warnings for dropped URL parts, and canonical endpoint URL output.
+- Update SmartBucket (ts/classes.smartbucket.ts) to use the normalized endpoint, region, credentials and forcePathStyle from normalizeS3Descriptor.
+- Adjust dev tooling: bump @git.zone/tsbuild -> ^2.6.7, @git.zone/tstest -> ^2.3.4, @push.rocks/qenv -> ^6.1.3 and update test script to run tstest with --verbose --logfile --timeout 60.
+- Add .claude/settings.local.json containing local assistant/CI permission settings (local config only).
+
+## 2025-08-15 - 3.3.9 - fix(docs)
+Revise README with detailed usage examples and add local Claude settings
+
+- Revamped README: reorganized content, added emojis and clearer headings for install, getting started, bucket/file/directory operations, streaming, metadata, trash/recovery, locking, and advanced configuration.
+- Added many concrete code examples for SmartBucket, Bucket, Directory, File, streaming (node/web), RxJS replay subjects, metadata handling, trash workflow, file locking, magic-bytes detection, JSON operations, and cleaning bucket contents.
+- Included testing instructions (pnpm test) and a Best Practices section with recommendations for strict mode, streaming, metadata, trash usage, and locking.
+- Added .claude/settings.local.json to include local Claude configuration and tool permissions.
+- No source code or public API changes; documentation and local tooling config only.
+
+## 2025-08-15 - 3.3.8 - fix(tests)
+Update tests to use @git.zone/tstest, upgrade dependencies, remove GitLab CI and add local CI/workspace config
+
+- Tests: replace imports from @push.rocks/tapbundle with @git.zone/tstest/tapbundle and switch tap.start() to export default tap.start()
+- Dependencies: bump @aws-sdk/client-s3 and several @push.rocks packages; upgrade @tsclass/tsclass to a newer major
+- DevDependencies: upgrade @git.zone/tsbuild, @git.zone/tstest, @push.rocks/qenv, and @push.rocks/tapbundle
+- CI/config: remove .gitlab-ci.yml, add .claude/settings.local.json
+- Workspace: add pnpm-workspace.yaml and packageManager field in package.json
+
+## 2024-12-02 - 3.3.7 - fix(package)
+Update author field in package.json
+
+- Corrected the author field from 'Lossless GmbH' to 'Task Venture Capital GmbH' in the package.json file.
+
+## 2024-12-02 - 3.3.6 - fix(package)
+Fix license field in package.json to reflect MIT licensing
+
+
+## 2024-11-25 - 3.3.5 - fix(test)
+Refactor trash test to improve metadata validation
+
+- Added new checks in trash tests to ensure metadata files are correctly moved to trash.
+- Validated the presence and integrity of metadata within trashed files.
+
+## 2024-11-25 - 3.3.4 - fix(core)
+Minor refactoring and cleanup of TypeScript source files for improved readability and maintainability.
+
+
+## 2024-11-24 - 3.3.3 - fix(documentation)
+Improved documentation accuracy and consistency
+
+- Updated the project description to reflect the cloud-agnostic nature and advanced capabilities
+- Enhanced the README with detailed explanations and code examples for advanced features like trash management
+- Clarified the handling and importance of metadata using the MetaData utility
+
+## 2024-11-24 - 3.3.2 - fix(documentation)
+Updated keywords and description for clarity and consistency.
+
+- Modified keywords and description in package.json and npmextra.json.
+- Enhanced readme.md file structure and examples
+
+## 2024-11-24 - 3.3.1 - fix(File)
+Fixed issue with file restore metadata operations.
+
+- Corrected the order of operations in the file restore function to ensure custom metadata is appropriately deleted after moving the file.
+
+## 2024-11-24 - 3.3.0 - feat(core)
+Enhanced directory handling and file restoration from trash
+
+- Refined getSubDirectoryByName to handle file paths treated as directories.
+- Introduced file restoration function from trash to original or specified paths.
+
+## 2024-11-24 - 3.2.2 - fix(core)
+Refactor Bucket class for improved error handling
+
+- Ensured safe access using non-null assertions when finding a bucket.
+- Enhanced fastPut method by adding fastPutStrict for safer operations.
+- Added explicit error handling and type checking in fastExists method.
+
+## 2024-11-24 - 3.2.1 - fix(metadata)
+Fix metadata handling for deleted files
+
+- Ensured metadata is correctly stored and managed when files are deleted into the trash.
+
+## 2024-11-24 - 3.2.0 - feat(bucket)
+Enhanced SmartBucket with trash management and metadata handling
+
+- Added functionality to move files to a trash directory.
+- Introduced methods to handle file metadata more robustly.
+- Implemented a method to clean all contents from a bucket.
+- Enhanced directory retrieval to handle non-existent directories with options.
+- Improved handling of file paths and metadata within the storage system.
+
+## 2024-11-18 - 3.1.0 - feat(file)
+Added functionality to retrieve magic bytes from files and detect file types using magic bytes.
+
+- Introduced method `getMagicBytes` in `File` and `Bucket` classes to retrieve a specific number of bytes from a file.
+- Enhanced file type detection by utilizing magic bytes in `MetaData` class.
+- Updated dependencies for better performance and compatibility.
+
+## 2024-11-18 - 3.0.24 - fix(metadata)
+Fix metadata handling to address type assertion and data retrieval.
+
+- Fixed type assertion issues in `MetaData` class properties with type non-null assertions.
+- Corrected the handling of JSON data retrieval in `MetaData.storeCustomMetaData` function.
+
+## 2024-10-16 - 3.0.23 - fix(dependencies)
+Update package dependencies for improved functionality and security.
+
+- Updated @aws-sdk/client-s3 to version ^3.670.0 for enhanced S3 client capabilities.
+- Updated @push.rocks/smartstream to version ^3.2.4.
+- Updated the dev dependency @push.rocks/tapbundle to version ^5.3.0.
+
+## 2024-07-28 - 3.0.22 - fix(dependencies)
+Update dependencies and improve bucket retrieval logging
+
+- Updated @aws-sdk/client-s3 to ^3.620.0
+- Updated @git.zone/tsbuild to ^2.1.84
+- Updated @git.zone/tsrun to ^1.2.49
+- Updated @push.rocks/smartpromise to ^4.0.4
+- Updated @tsclass/tsclass to ^4.1.2
+- Added a log for when a bucket is not found by name in getBucketByName method
+
+## 2024-07-04 - 3.0.21 - fix(test)
+Update endpoint configuration in tests to use environment variable
+
+- Modified `qenv.yml` to include `S3_ENDPOINT` as a required environment variable.
+- Updated test files to fetch `S3_ENDPOINT` from environment instead of hardcoding.
+
+## 2024-06-19 - 3.0.20 - Fix and Stability Updates
+Improved overall stability and consistency.
+
+## 2024-06-18 - 3.0.18 - Delete Functions Consistency
+Ensured more consistency between delete methods and trash behavior.
+
+## 2024-06-17 - 3.0.17 to 3.0.16 - Fix and Update
+Routine updates and fixes performed.
+
+## 2024-06-11 - 3.0.15 to 3.0.14 - Fix and Update
+Routine updates and fixes performed.
+
+## 2024-06-10 - 3.0.13 - Trash Feature Completion
+Finished work on trash feature.
+
+## 2024-06-09 - 3.0.12 - Fix and Update
+Routine updates and fixes performed.
+
+## 2024-06-08 - 3.0.11 to 3.0.10 - Fix and Update
+Routine updates and fixes performed.
+
+## 2024-06-03 - 3.0.10 - Fix and Update
+Routine updates and fixes performed.
+
+## 2024-05-29 - 3.0.9 - Update Description
+Updated project description.
+
+## 2024-05-27 - 3.0.8 to 3.0.6 - Pathing and Core Updates
+Routine updates and fixes performed.
+  - S3 paths' pathing differences now correctly handled with a reducePath method.
+
+## 2024-05-21 - 3.0.5 to 3.0.4 - Fix and Update
+Routine updates and fixes performed.
+
+## 2024-05-17 - 3.0.3 to 3.0.2 - Fix and Update
+Routine updates and fixes performed.
+
+## 2024-05-17 - 3.0.0 - Major Release
+Introduced breaking changes in core and significant improvements.
+
+## 2024-05-05 - 2.0.5 - Breaking Changes
+Introduced breaking changes in core functionality.
+
+## 2024-04-14 - 2.0.4 - TSConfig Update
+Updated TypeScript configuration.
+
+## 2024-01-01 - 2.0.2 - Organization Scheme Update
+Switched to the new organizational scheme.
--- a/deno.lock
+++ b/deno.lock
--- a/19
+++ b/19
@@ -0,0 +1,19 @@
+Copyright (c) 2014 Task Venture Capital GmbH (hello@task.vc)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
--- a/npmextra.json
+++ b/npmextra.json
@@ -8,25 +8,30 @@
      "githost": "code.foss.global",
      "gitscope": "push.rocks",
      "gitrepo": "smartbucket",
-      "description": "A TypeScript library that offers simple, cloud-independent object storage with features like bucket creation, file management, and directory management.",
+      "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.",
      "npmPackagename": "@push.rocks/smartbucket",
      "license": "MIT",
      "keywords": [
-        "cloud storage",
-        "object storage",
        "TypeScript",
-        "S3",
-        "minio",
-        "file management",
+        "cloud agnostic",
+        "object storage",
+        "bucket management",
+        "file operations",
        "directory management",
-        "bucket creation",
        "data streaming",
+        "S3",
        "multi-cloud",
-        "API",
-        "unified storage",
+        "file locking",
+        "metadata management",
        "buffer handling",
-        "access key",
-        "secret key"
+        "access control",
+        "environment configuration",
+        "unified storage",
+        "bucket policies",
+        "trash management",
+        "file transfer",
+        "data management",
+        "streaming"
      ]
    }
  },
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
  "name": "@push.rocks/smartbucket",
-  "version": "3.0.5",
+  "version": "3.3.10",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "@push.rocks/smartbucket",
-      "version": "3.0.5",
+      "version": "3.3.10",
      "license": "UNLICENSED",
      "dependencies": {
        "@push.rocks/smartpath": "^5.0.18",
--- a/package.json
+++ b/package.json
@@ -1,31 +1,34 @@
 {
  "name": "@push.rocks/smartbucket",
-  "version": "3.0.5",
-  "description": "A TypeScript library that offers simple, cloud-independent object storage with features like bucket creation, file management, and directory management.",
+  "version": "4.3.0",
+  "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",
  "type": "module",
-  "author": "Lossless GmbH",
-  "license": "UNLICENSED",
+  "author": "Task Venture Capital GmbH",
+  "license": "MIT",
  "scripts": {
-    "test": "(tstest test/)",
+    "test": "(tstest test/ --verbose --logfile --timeout 120)",
    "build": "(tsbuild --web --allowimplicitany)"
  },
  "devDependencies": {
-    "@git.zone/tsbuild": "^2.1.80",
-    "@git.zone/tsrun": "^1.2.46",
-    "@git.zone/tstest": "^1.0.90",
-    "@push.rocks/qenv": "^6.0.5",
-    "@push.rocks/tapbundle": "^5.0.23"
+    "@git.zone/tsbuild": "^3.1.0",
+    "@git.zone/tsrun": "^2.0.0",
+    "@git.zone/tstest": "^3.0.1",
+    "@push.rocks/qenv": "^6.1.3",
+    "@push.rocks/tapbundle": "^6.0.3"
  },
  "dependencies": {
-    "@push.rocks/smartmime": "^2.0.0",
-    "@push.rocks/smartpath": "^5.0.18",
-    "@push.rocks/smartpromise": "^4.0.3",
-    "@push.rocks/smartrx": "^3.0.7",
-    "@push.rocks/smartstream": "^3.0.38",
-    "@tsclass/tsclass": "^4.0.54",
-    "minio": "^8.0.0"
+    "@aws-sdk/client-s3": "^3.936.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/smartstring": "^4.1.0",
+    "@push.rocks/smartunique": "^3.0.9",
+    "@tsclass/tsclass": "^9.3.0",
+    "minimatch": "^10.1.1"
  },
  "private": false,
  "files": [
@@ -44,20 +47,31 @@
    "last 1 chrome versions"
  ],
  "keywords": [
-    "cloud storage",
-    "object storage",
    "TypeScript",
-    "S3",
-    "minio",
-    "file management",
+    "cloud agnostic",
+    "object storage",
+    "bucket management",
+    "file operations",
    "directory management",
-    "bucket creation",
    "data streaming",
+    "S3",
    "multi-cloud",
-    "API",
-    "unified storage",
+    "file locking",
+    "metadata management",
    "buffer handling",
-    "access key",
-    "secret key"
-  ]
+    "access control",
+    "environment configuration",
+    "unified storage",
+    "bucket policies",
+    "trash management",
+    "file transfer",
+    "data management",
+    "streaming"
+  ],
+  "homepage": "https://code.foss.global/push.rocks/smartbucket",
+  "repository": {
+    "type": "git",
+    "url": "https://code.foss.global/push.rocks/smartbucket.git"
+  },
+  "packageManager": "pnpm@10.14.0+sha512.ad27a79641b49c3e481a16a805baa71817a04bbe06a38d17e60e2eaee83f6a146c6a688125f5792e48dd5ba30e7da52a5cda4c3992b9ccf333f9ce223af84748"
 }
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -0,0 +1,4 @@
+onlyBuiltDependencies:
+  - esbuild
+  - mongodb-memory-server
+  - puppeteer
--- a/qenv.yml
+++ b/qenv.yml
@@ -1,3 +1,4 @@
 required:
  - S3_KEY
-  - S3_SECRET
+  - S3_SECRET
+  - S3_ENDPOINT
--- a/readme.hints.md
+++ b/readme.hints.md
@@ -1 +1,5 @@
- 
+* The project uses the official s3 client, not the minio client.
+* **All methods throw by default** (strict mode):  - Put operations: `fastPut`, `fastPutStream` throw when file exists and overwrite is false  - Get operations: `getBucketByName`, `getFile`, `getSubDirectoryByName` throw when not found
+* **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!
--- a/readme.md
+++ b/readme.md
--- a/test/helpers/prepare.ts
+++ b/test/helpers/prepare.ts
--- 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'),
+    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 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 FakeS3Client {
+  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 = { s3Client: new FakeS3Client([{ 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 = { s3Client: new FakeS3Client([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 = {
+    s3Client: new FakeS3Client([
+      { 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.metadata.node+deno.ts
+++ b/test/test.metadata.node+deno.ts
@@ -0,0 +1,7 @@
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+
+tap.test('test metadata functionality', async () => {
+
+})
+
+export default tap.start();
--- a/test/test.node+deno.ts
+++ b/test/test.node+deno.ts
@@ -1,4 +1,4 @@
-import { expect, expectAsync, tap } from '@push.rocks/tapbundle';
+import { expect, tap } from '@git.zone/tstest/tapbundle';
 import { Qenv } from '@push.rocks/qenv';

 import * as smartbucket from '../ts/index.js';
@@ -11,24 +11,31 @@ let baseDirectory: smartbucket.Directory;

 tap.test('should create a valid smartbucket', async () => {
  testSmartbucket = new smartbucket.SmartBucket({
-    accessKey: await testQenv.getEnvVarOnDemand('S3_KEY'),
-    accessSecret: await testQenv.getEnvVarOnDemand('S3_SECRET'),
-    endpoint: 's3.eu-central-1.wasabisys.com',
+    accessKey: await testQenv.getEnvVarOnDemandStrict('S3_ACCESSKEY'),
+    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);
+  const bucketName = await testQenv.getEnvVarOnDemandStrict('S3_BUCKET');
+  myBucket = await testSmartbucket.getBucketByName(bucketName);
+  expect(myBucket).toBeInstanceOf(smartbucket.Bucket);
+  expect(myBucket.name).toEqual(bucketName);
+});
+
+tap.test('should clean all contents', async () => {
+  await myBucket.cleanAllContents();
+  expect(await myBucket.fastExists({ path: 'hithere/socool.txt' })).toBeFalse();
+  expect(await myBucket.fastExists({ path: 'trashtest/trashme.txt' })).toBeFalse();
 });

 tap.skip.test('should create testbucket', async () => {
-  // await testSmartbucket.createBucket('testzone');
+  // await testSmartbucket.createBucket('testzone2');
 });

 tap.skip.test('should remove testbucket', async () => {
-  // await testSmartbucket.removeBucket('testzone');
-});
-
-tap.test('should get a bucket', async () => {
-  myBucket = await testSmartbucket.getBucketByName('testzone');
-  expect(myBucket).toBeInstanceOf(smartbucket.Bucket);
-  expect(myBucket.name).toEqual('testzone');
+  // await testSmartbucket.removeBucket('testzone2');
 });

 // Fast operations
@@ -43,9 +50,12 @@ tap.test('should get data in bucket', async () => {
  const fileString = await myBucket.fastGet({
    path: 'hithere/socool.txt',
  });
-  const fileStringStream = await myBucket.fastGetStream({
-    path: 'hithere/socool.txt',
-  });
+  const fileStringStream = await myBucket.fastGetStream(
+    {
+      path: 'hithere/socool.txt',
+    },
+    'nodestream'
+  );
  console.log(fileString);
 });

@@ -79,7 +89,7 @@ tap.test('prepare for directory style tests', async () => {
    contents: 'dir3/dir4/file1.txt content',
  });
  await myBucket.fastPut({
-    path: 'file1.txt',
+    path: '/file1.txt',
    contents: 'file1 content',
  });
 });
@@ -99,8 +109,9 @@ tap.test('should get base directory', async () => {
 tap.test('should correctly build paths for sub directories', async () => {
  const dir4 = await baseDirectory.getSubDirectoryByName('dir3/dir4');
  expect(dir4).toBeInstanceOf(smartbucket.Directory);
-  const dir4BasePath = dir4.getBasePath();
+  const dir4BasePath = dir4?.getBasePath();
  console.log(dir4BasePath);
+  expect(dir4BasePath).toEqual('dir3/dir4/');
 });

 tap.test('clean up directory style tests', async () => {
@@ -118,4 +129,4 @@ tap.test('clean up directory style tests', async () => {
  await myBucket.fastRemove({ path: 'file1.txt' });
 });

-tap.start();
+export default tap.start();
--- a/test/test.trash.node+deno.ts
+++ b/test/test.trash.node+deno.ts
@@ -0,0 +1,94 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import { jestExpect } from '@push.rocks/tapbundle/node';
+import { Qenv } from '@push.rocks/qenv';
+
+import * as smartbucket from '../ts/index.js';
+
+const testQenv = new Qenv('./', './.nogit/');
+
+let testSmartbucket: smartbucket.SmartBucket;
+let myBucket: smartbucket.Bucket;
+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_SECRETKEY'),
+    endpoint: await testQenv.getEnvVarOnDemandStrict('S3_ENDPOINT'),
+    port: parseInt(await testQenv.getEnvVarOnDemandStrict('S3_PORT')),
+    useSsl: false,
+  });
+  expect(testSmartbucket).toBeInstanceOf(smartbucket.SmartBucket);
+  const bucketName = await testQenv.getEnvVarOnDemandStrict('S3_BUCKET');
+  myBucket = await testSmartbucket.getBucketByName(bucketName);
+  expect(myBucket).toBeInstanceOf(smartbucket.Bucket);
+});
+
+tap.test('should clean all contents', async () => {
+  await myBucket.cleanAllContents();
+  expect(await myBucket.fastExists({ path: 'hithere/socool.txt' })).toBeFalse();
+  expect(await myBucket.fastExists({ path: 'trashtest/trashme.txt' })).toBeFalse();
+});
+
+tap.test('should delete a file into the normally', async () => {
+  const path = 'trashtest/trashme.txt';
+  const file = await myBucket.fastPut({
+    path,
+    contents: 'I\'m in the trash test content!',
+  });
+  const fileMetadata = await (await file.getMetaData()).metadataFile.getContents();
+  console.log(fileMetadata.toString());
+  expect(await file.getMetaData().then((meta) => meta.metadataFile.getJsonData())).toEqual({});
+  await file.delete({ mode: 'permanent' });
+  expect((await (await myBucket.getBaseDirectory()).listFiles()).length).toEqual(0);  
+  expect((await (await myBucket.getBaseDirectory()).listDirectories()).length).toEqual(0);  
+});
+
+tap.test('should put a file into the trash', async () => {
+  const path = 'trashtest/trashme.txt';
+  const file = await myBucket.fastPut({
+    path,
+    contents: 'I\'m in the trash test content!',
+  });
+  const fileMetadata = await (await file.getMetaData()).metadataFile.getContents();
+  console.log(fileMetadata.toString());
+  expect(await file.getMetaData().then((meta) => meta.metadataFile.getJsonData())).toEqual({});
+  await file.delete({ mode: 'trash' });
+
+  const getTrashContents = async () => {
+    const trash = await myBucket.getTrash();
+    const trashDir = await trash.getTrashDir();
+    return await trashDir.listFiles();
+  }
+
+  const trashedFiles = await getTrashContents();
+  expect(trashedFiles.length).toEqual(2);
+
+  const trashedMetaFile = trashedFiles.find(file => file.name.endsWith('.metadata'));
+  expect(trashedMetaFile).toBeDefined();
+  expect(trashedMetaFile).toBeInstanceOf(smartbucket.File);
+
+  jestExpect(await trashedMetaFile!.getJsonData()).toEqual({
+    custom_recycle: {
+      deletedAt: jestExpect.any(Number),
+      originalPath: "trashtest/trashme.txt",
+    },
+  });
+});
+
+tap.test('should restore a file from trash', async () => {
+  const baseDirectory = await myBucket.getBaseDirectory();
+  const file = await baseDirectory.getFile({
+    path: 'trashtest/trashme.txt',
+    getFromTrash: true
+  });
+  const trashFileMeta = await file.getMetaData();
+  const data = await trashFileMeta.getCustomMetaData({
+    key: 'recycle'
+  });
+  expect(file).toBeInstanceOf(smartbucket.File);
+  await file.restore();
+});
+
+
+export default tap.start();
--- a/ts/00_commitinfo_data.ts
+++ b/ts/00_commitinfo_data.ts
@@ -1,8 +1,8 @@
 /**
- * autocreated commitinfo by @pushrocks/commitinfo
+ * autocreated commitinfo by @push.rocks/commitinfo
 */
 export const commitinfo = {
  name: '@push.rocks/smartbucket',
-  version: '3.0.5',
-  description: 'A TypeScript library that offers simple, cloud-independent object storage with features like bucket creation, file management, and directory management.'
+  version: '4.3.0',
+  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
@@ -1,30 +1,43 @@
+// classes.bucket.ts
+
 import * as plugins from './plugins.js';
+import * as helpers from './helpers.js';
+import * as interfaces from './interfaces.js';
 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';

+/**
+ * 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.
+ */
 export class Bucket {
-  public static async getBucketByName(smartbucketRef: SmartBucket, bucketNameArg: string) {
-    const buckets = await smartbucketRef.minioClient.listBuckets();
-    const foundBucket = buckets.find((bucket) => {
-      return bucket.name === bucketNameArg;
-    });
+  public static async getBucketByName(smartbucketRef: SmartBucket, bucketNameArg: string): Promise<Bucket> {
+    const command = new plugins.s3.ListBucketsCommand({});
+    const buckets = await smartbucketRef.s3Client.send(command);
+    const foundBucket = buckets.Buckets!.find((bucket) => bucket.Name === bucketNameArg);

    if (foundBucket) {
      console.log(`bucket with name ${bucketNameArg} exists.`);
      console.log(`Taking this as base for new Bucket instance`);
      return new this(smartbucketRef, bucketNameArg);
    } else {
-      return null;
+      throw new Error(`Bucket '${bucketNameArg}' not found.`);
    }
  }

  public static async createBucketByName(smartbucketRef: SmartBucket, bucketName: string) {
-    await smartbucketRef.minioClient.makeBucket(bucketName, 'ams3').catch((e) => console.log(e));
+    const command = new plugins.s3.CreateBucketCommand({ Bucket: bucketName });
+    await smartbucketRef.s3Client.send(command).catch((e) => console.log(e));
    return new Bucket(smartbucketRef, bucketName);
  }

  public static async removeBucketByName(smartbucketRef: SmartBucket, bucketName: string) {
-    await smartbucketRef.minioClient.removeBucket(bucketName).catch((e) => console.log(e));
+    const command = new plugins.s3.DeleteBucketCommand({ Bucket: bucketName });
+    await smartbucketRef.s3Client.send(command).catch((e) => console.log(e));
  }

  public smartbucketRef: SmartBucket;
@@ -38,8 +51,29 @@ export class Bucket {
  /**
   * gets the base directory of the bucket
   */
-  public async getBaseDirectory() {
-    return new Directory(this, null, '');
+  public async getBaseDirectory(): Promise<Directory> {
+    return new Directory(this, null!, '');
+  }
+
+  /**
+   * gets the trash directory
+   */
+  public async getTrash(): Promise<Trash> {
+    const trash = new Trash(this);
+    return trash;
+  }
+
+  public async getDirectoryFromPath(
+    pathDescriptorArg: interfaces.IPathDecriptor
+  ): Promise<Directory> {
+    if (!pathDescriptorArg.path && !pathDescriptorArg.directory) {
+      return this.getBaseDirectory();
+    }
+    const checkPath = await helpers.reducePathDescriptorToPath(pathDescriptorArg);
+    const baseDirectory = await this.getBaseDirectory();
+    return await baseDirectory.getSubDirectoryByName(checkPath, {
+      getEmptyDirectory: true,
+    });
  }

  // ===============
@@ -49,46 +83,61 @@ export class Bucket {
  /**
   * store file
   */
-  public async fastPut(optionsArg: {
-    path: string;
-    contents: string | Buffer;
-    overwrite?: boolean;
-  }): Promise<void> {
+  public async fastPut(
+    optionsArg: interfaces.IPathDecriptor & {
+      contents: string | Buffer;
+      overwrite?: boolean;
+    }
+  ): Promise<File> {
    try {
-      // Check if the object already exists
-      const exists = await this.fastExists({ path: optionsArg.path });
-  
+      const reducedPath = await helpers.reducePathDescriptorToPath(optionsArg);
+      const exists = await this.fastExists({ path: reducedPath });
+
      if (exists && !optionsArg.overwrite) {
-        console.error(`Object already exists at path '${optionsArg.path}' in bucket '${this.name}'.`);
-        return;
+        throw new Error(
+          `Object already exists at path '${reducedPath}' in bucket '${this.name}'. ` +
+          `Set overwrite:true to replace it.`
+        );
      } else if (exists && optionsArg.overwrite) {
-        console.log(`Overwriting existing object at path '${optionsArg.path}' in bucket '${this.name}'.`);
+        console.log(
+          `Overwriting existing object at path '${reducedPath}' in bucket '${this.name}'.`
+        );
      } else {
-        console.log(`Creating new object at path '${optionsArg.path}' in bucket '${this.name}'.`);
+        console.log(`Creating new object at path '${reducedPath}' in bucket '${this.name}'.`);
      }
-  
-      // Proceed with putting the object
-      const streamIntake = new plugins.smartstream.StreamIntake();
-      const putPromise = this.smartbucketRef.minioClient.putObject(this.name, optionsArg.path, streamIntake);
-      streamIntake.pushData(optionsArg.contents);
-      streamIntake.signalEnd();
-      await putPromise;
-  
-      console.log(`Object '${optionsArg.path}' has been successfully stored in bucket '${this.name}'.`);
+
+      const command = new plugins.s3.PutObjectCommand({
+        Bucket: this.name,
+        Key: reducedPath,
+        Body: optionsArg.contents,
+      });
+      await this.smartbucketRef.s3Client.send(command);
+
+      console.log(`Object '${reducedPath}' has been successfully stored in bucket '${this.name}'.`);
+      const parsedPath = plugins.path.parse(reducedPath);
+      return new File({
+        directoryRefArg: await this.getDirectoryFromPath({
+          path: parsedPath.dir,
+        }),
+        fileName: parsedPath.base,
+      });
    } catch (error) {
-      console.error(`Error storing object at path '${optionsArg.path}' in bucket '${this.name}':`, error);
+      console.error(
+        `Error storing object at path '${optionsArg.path}' in bucket '${this.name}':`,
+        error
+      );
      throw error;
    }
  }
-  
+

  /**
   * get file
   */
-  public async fastGet(optionsArg: Parameters<typeof this.fastGetStream>[0]): Promise<Buffer> {
+  public async fastGet(optionsArg: { path: string }): Promise<Buffer> {
    const done = plugins.smartpromise.defer();
    let completeFile: Buffer;
-    const replaySubject = await this.fastGetStream(optionsArg);
+    const replaySubject = await this.fastGetReplaySubject(optionsArg);
    const subscription = replaySubject.subscribe({
      next: (chunk) => {
        if (completeFile) {
@@ -106,96 +155,140 @@ export class Bucket {
      },
    });
    await done.promise;
-    return completeFile;
+    return completeFile!;
  }

-  public async fastGetStream(optionsArg: {
+  /**
+   * good when time to first byte is important
+   * and multiple subscribers are expected
+   * @param optionsArg
+   * @returns
+   */
+  public async fastGetReplaySubject(optionsArg: {
    path: string;
  }): Promise<plugins.smartrx.rxjs.ReplaySubject<Buffer>> {
-    const fileStream = await this.smartbucketRef.minioClient
-      .getObject(this.name, optionsArg.path)
-      .catch((e) => console.log(e));
-    const replaySubject = new plugins.smartrx.rxjs.ReplaySubject<Buffer>();
-    const duplexStream = new plugins.smartstream.SmartDuplex<Buffer, void>({
-      writeFunction: async (chunk) => {
-        replaySubject.next(chunk);
-        return;
-      },
-      finalFunction: async (cb) => {
-        replaySubject.complete();
-        return;
-      }
+    const command = new plugins.s3.GetObjectCommand({
+      Bucket: this.name,
+      Key: optionsArg.path,
    });
+    const response = await this.smartbucketRef.s3Client.send(command);
+    const replaySubject = new plugins.smartrx.rxjs.ReplaySubject<Buffer>();

-    if (!fileStream) {
-      return null;
+    // Convert the stream to a format that supports piping
+    const stream = response.Body as any; // SdkStreamMixin includes readable stream
+    if (typeof stream.pipe === 'function') {
+      const duplexStream = new plugins.smartstream.SmartDuplex<Buffer, void>({
+        writeFunction: async (chunk) => {
+          replaySubject.next(chunk);
+          return;
+        },
+        finalFunction: async (cb) => {
+          replaySubject.complete();
+          return;
+        },
+      });
+
+      stream.pipe(duplexStream);
    }

-    const smartstream = new plugins.smartstream.StreamWrapper([
-      fileStream,
-      duplexStream,
-    ]);
-    smartstream.run();
    return replaySubject;
  }

+  public fastGetStream(
+    optionsArg: {
+      path: string;
+    },
+    typeArg: 'webstream'
+  ): Promise<ReadableStream>;
+  public async fastGetStream(
+    optionsArg: {
+      path: string;
+    },
+    typeArg: 'nodestream'
+  ): Promise<plugins.stream.Readable>;
+
+  public async fastGetStream(
+    optionsArg: { path: string },
+    typeArg: 'webstream' | 'nodestream' = 'nodestream'
+  ): Promise<ReadableStream | plugins.stream.Readable> {
+    const command = new plugins.s3.GetObjectCommand({
+      Bucket: this.name,
+      Key: optionsArg.path,
+    });
+    const response = await this.smartbucketRef.s3Client.send(command);
+    const stream = response.Body as any; // SdkStreamMixin includes readable stream
+
+    const duplexStream = new plugins.smartstream.SmartDuplex<Buffer, Buffer>({
+      writeFunction: async (chunk) => {
+        return chunk;
+      },
+      finalFunction: async (cb) => {
+        return null!;
+      },
+    });
+
+    if (typeof stream.pipe === 'function') {
+      stream.pipe(duplexStream);
+    }
+
+    if (typeArg === 'nodestream') {
+      return duplexStream;
+    }
+    if (typeArg === 'webstream') {
+      return (await duplexStream.getWebStreams()).readable;
+    }
+    throw new Error('unknown typeArg');
+  }
+
  /**
   * store file as stream
   */
  public async fastPutStream(optionsArg: {
    path: string;
-    dataStream: plugins.stream.Readable;
+    readableStream: plugins.stream.Readable | ReadableStream;
    nativeMetadata?: { [key: string]: string };
    overwrite?: boolean;
  }): Promise<void> {
    try {
-      // Check if the object already exists
      const exists = await this.fastExists({ path: optionsArg.path });
-  
+
      if (exists && !optionsArg.overwrite) {
-        console.error(`Object already exists at path '${optionsArg.path}' in bucket '${this.name}'.`);
-        return;
+        throw new Error(
+          `Object already exists at path '${optionsArg.path}' in bucket '${this.name}'. ` +
+          `Set overwrite:true to replace it.`
+        );
      } else if (exists && optionsArg.overwrite) {
-        console.log(`Overwriting existing object at path '${optionsArg.path}' in bucket '${this.name}'.`);
+        console.log(
+          `Overwriting existing object at path '${optionsArg.path}' in bucket '${this.name}'.`
+        );
      } else {
        console.log(`Creating new object at path '${optionsArg.path}' in bucket '${this.name}'.`);
      }
-  
-      // Proceed with putting the object
-      await this.smartbucketRef.minioClient.putObject(
-        this.name,
-        optionsArg.path,
-        optionsArg.dataStream,
-        null,
-        ...(optionsArg.nativeMetadata
-          ? (() => {
-              const returnObject: any = {};
-              return returnObject;
-            })()
-          : {})
+
+      const command = new plugins.s3.PutObjectCommand({
+        Bucket: this.name,
+        Key: optionsArg.path,
+        Body: optionsArg.readableStream,
+        Metadata: optionsArg.nativeMetadata,
+      });
+      await this.smartbucketRef.s3Client.send(command);
+
+      console.log(
+        `Object '${optionsArg.path}' has been successfully stored in bucket '${this.name}'.`
      );
-  
-      console.log(`Object '${optionsArg.path}' has been successfully stored in bucket '${this.name}'.`);
    } catch (error) {
-      console.error(`Error storing object at path '${optionsArg.path}' in bucket '${this.name}':`, error);
+      console.error(
+        `Error storing object at path '${optionsArg.path}' in bucket '${this.name}':`,
+        error
+      );
      throw error;
    }
  }
-  

-  public async copyObject(optionsArg: {
-    /**
-     * the
-     */
-    objectKey: string;
-    /**
-     * in case you want to copy to another bucket specify it here
-     */
+  public async fastCopy(optionsArg: {
+    sourcePath: string;
+    destinationPath?: string;
    targetBucket?: Bucket;
-    targetBucketKey?: string;
-    /**
-     * metadata will be merged with existing metadata
-     */
    nativeMetadata?: { [key: string]: string };
    deleteExistingNativeMetadata?: boolean;
  }): Promise<void> {
@@ -203,28 +296,29 @@ 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.minioClient.statObject(
-        targetBucketName,
-        optionsArg.objectKey
+      const currentObjInfo = await this.smartbucketRef.s3Client.send(
+        new plugins.s3.HeadObjectCommand({
+          Bucket: this.name,
+          Key: optionsArg.sourcePath,
+        })
      );

-      // Setting up copy conditions
-      const copyConditions = new plugins.minio.CopyConditions();
-
      // Prepare new metadata
      const newNativeMetadata = {
-        ...(optionsArg.deleteExistingNativeMetadata ? {} : currentObjInfo.metaData),
+        ...(optionsArg.deleteExistingNativeMetadata ? {} : currentObjInfo.Metadata),
        ...optionsArg.nativeMetadata,
      };

-      // Define the copy operation as a Promise
-      // TODO: check on issue here: https://github.com/minio/minio-js/issues/1286
-      await this.smartbucketRef.minioClient.copyObject(
-        this.name,
-        optionsArg.objectKey,
-        `/${targetBucketName}/${optionsArg.objectKey}`,
-        copyConditions
-      );
+      // Define the copy operation
+      const copySource = `${this.name}/${optionsArg.sourcePath}`;
+      const command = new plugins.s3.CopyObjectCommand({
+        Bucket: targetBucketName,
+        CopySource: copySource,
+        Key: optionsArg.destinationPath || optionsArg.sourcePath,
+        Metadata: newNativeMetadata,
+        MetadataDirective: optionsArg.deleteExistingNativeMetadata ? 'REPLACE' : 'COPY',
+      });
+      await this.smartbucketRef.s3Client.send(command);
    } catch (err) {
      console.error('Error updating metadata:', err);
      throw err; // rethrow to allow caller to handle
@@ -232,28 +326,77 @@ export class Bucket {
  }

  /**
-   * removeObject
+   * Move object from one path to another within the same bucket or to another bucket
   */
-  public async fastRemove(optionsArg: {
-    path: string;
-  }) {
-    await this.smartbucketRef.minioClient.removeObject(this.name, optionsArg.path);
+  public async fastMove(optionsArg: {
+    sourcePath: string;
+    destinationPath: string;
+    targetBucket?: Bucket;
+    overwrite?: boolean;
+  }): Promise<void> {
+    try {
+      const destinationBucket = optionsArg.targetBucket || this;
+      const exists = await destinationBucket.fastExists({
+        path: optionsArg.destinationPath,
+      });
+
+      if (exists && !optionsArg.overwrite) {
+        console.error(
+          `Object already exists at destination path '${optionsArg.destinationPath}' in bucket '${destinationBucket.name}'.`
+        );
+        return;
+      } else if (exists && optionsArg.overwrite) {
+        console.log(
+          `Overwriting existing object at destination path '${optionsArg.destinationPath}' in bucket '${destinationBucket.name}'.`
+        );
+      } else {
+        console.log(
+          `Moving object to path '${optionsArg.destinationPath}' in bucket '${destinationBucket.name}'.`
+        );
+      }
+
+      await this.fastCopy(optionsArg);
+      await this.fastRemove({ path: optionsArg.sourcePath });
+
+      console.log(
+        `Object '${optionsArg.sourcePath}' has been successfully moved to '${optionsArg.destinationPath}' in bucket '${destinationBucket.name}'.`
+      );
+    } catch (error) {
+      console.error(
+        `Error moving object from '${optionsArg.sourcePath}' to '${optionsArg.destinationPath}':`,
+        error
+      );
+      throw error;
+    }
  }

  /**
-   * check wether file exists
-   * @param optionsArg
-   * @returns 
+   * removeObject
   */
-  public async fastExists(optionsArg: {
-    path: string;
-  }): Promise<boolean> {
+  public async fastRemove(optionsArg: { path: string }) {
+    const command = new plugins.s3.DeleteObjectCommand({
+      Bucket: this.name,
+      Key: optionsArg.path,
+    });
+    await this.smartbucketRef.s3Client.send(command);
+  }
+
+  /**
+   * check whether file exists
+   * @param optionsArg
+   * @returns
+   */
+  public async fastExists(optionsArg: { path: string }): Promise<boolean> {
    try {
-      await this.smartbucketRef.minioClient.statObject(this.name, optionsArg.path);
+      const command = new plugins.s3.HeadObjectCommand({
+        Bucket: this.name,
+        Key: optionsArg.path,
+      });
+      await this.smartbucketRef.s3Client.send(command);
      console.log(`Object '${optionsArg.path}' exists in bucket '${this.name}'.`);
      return true;
-    } catch (error) {
-      if (error.code === 'NotFound') {
+    } catch (error: any) {
+      if (error?.name === 'NotFound') {
        console.log(`Object '${optionsArg.path}' does not exist in bucket '${this.name}'.`);
        return false;
      } else {
@@ -263,9 +406,254 @@ export class Bucket {
    }
  }

-  public async fastStat(optionsArg: {
-    path: string;
-  }) {
-    return this.smartbucketRef.minioClient.statObject(this.name, optionsArg.path);
+  /**
+   * deletes this bucket
+   */
+  public async delete() {
+    await this.smartbucketRef.s3Client.send(
+      new plugins.s3.DeleteBucketCommand({ Bucket: this.name })
+    );
+  }
+
+  public async fastStat(pathDescriptor: interfaces.IPathDecriptor) {
+    const checkPath = await helpers.reducePathDescriptorToPath(pathDescriptor);
+    const command = new plugins.s3.HeadObjectCommand({
+      Bucket: this.name,
+      Key: checkPath,
+    });
+    return this.smartbucketRef.s3Client.send(command);
+  }
+
+  public async isDirectory(pathDescriptor: interfaces.IPathDecriptor): Promise<boolean> {
+    const checkPath = await helpers.reducePathDescriptorToPath(pathDescriptor);
+    const command = new plugins.s3.ListObjectsV2Command({
+      Bucket: this.name,
+      Prefix: checkPath,
+      Delimiter: '/',
+    });
+    const { CommonPrefixes } = await this.smartbucketRef.s3Client.send(command);
+    return !!CommonPrefixes && CommonPrefixes.length > 0;
+  }
+
+  public async isFile(pathDescriptor: interfaces.IPathDecriptor): Promise<boolean> {
+    const checkPath = await helpers.reducePathDescriptorToPath(pathDescriptor);
+    const command = new plugins.s3.ListObjectsV2Command({
+      Bucket: this.name,
+      Prefix: checkPath,
+      Delimiter: '/',
+    });
+    const { Contents } = await this.smartbucketRef.s3Client.send(command);
+    return !!Contents && Contents.length > 0;
+  }
+
+  public async getMagicBytes(optionsArg: { path: string; length: number }): Promise<Buffer> {
+    try {
+      const command = new plugins.s3.GetObjectCommand({
+        Bucket: this.name,
+        Key: optionsArg.path,
+        Range: `bytes=0-${optionsArg.length - 1}`,
+      });
+      const response = await this.smartbucketRef.s3Client.send(command);
+      const chunks: Buffer[] = [];
+      const stream = response.Body as any; // SdkStreamMixin includes readable stream
+
+      for await (const chunk of stream) {
+        chunks.push(chunk);
+      }
+      return Buffer.concat(chunks);
+    } catch (error) {
+      console.error(
+        `Error retrieving magic bytes from object at path '${optionsArg.path}' in bucket '${this.name}':`,
+        error
+      );
+      throw error;
+    }
+  }
+
+  // ==========================================
+  // 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.s3Client.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.s3Client.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);
+  }
+
+  // ==========================================
+  // 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
+      const listCommandInput: plugins.s3.ListObjectsV2CommandInput = {
+        Bucket: this.name,
+      };
+  
+      let isTruncated = true;
+      let continuationToken: string | undefined = undefined;
+  
+      while (isTruncated) {
+        // Add the continuation token to the input if present
+        const listCommand = new plugins.s3.ListObjectsV2Command({
+          ...listCommandInput,
+          ContinuationToken: continuationToken,
+        });
+  
+        // Explicitly type the response
+        const response: plugins.s3.ListObjectsV2Output =
+          await this.smartbucketRef.s3Client.send(listCommand);
+        
+        console.log(`Cleaning contents of bucket '${this.name}': Now deleting ${response.Contents?.length} items...`);
+
+        if (response.Contents && response.Contents.length > 0) {
+          // Delete objects in batches, mapping each item to { Key: string }
+          const deleteCommand = new plugins.s3.DeleteObjectsCommand({
+            Bucket: this.name,
+            Delete: {
+              Objects: response.Contents.map((item) => ({ Key: item.Key! })),
+              Quiet: true,
+            },
+          });
+  
+          await this.smartbucketRef.s3Client.send(deleteCommand);
+        }
+  
+        // Update continuation token and truncation status
+        isTruncated = response.IsTruncated || false;
+        continuationToken = response.NextContinuationToken;
+      }
+  
+      console.log(`All contents in bucket '${this.name}' have been deleted.`);
+    } catch (error) {
+      console.error(`Error cleaning contents of bucket '${this.name}':`, error);
+      throw error;
+    }
  }
 }
--- a/ts/classes.directory.ts
+++ b/ts/classes.directory.ts
@@ -1,19 +1,22 @@
+// classes.directory.ts
+
 import * as plugins from './plugins.js';
 import { Bucket } from './classes.bucket.js';
 import { File } from './classes.file.js';
+import * as helpers from './helpers.js';

 export class Directory {
  public bucketRef: Bucket;
  public parentDirectoryRef: Directory;
  public name: string;

-  public tree: string[];
-  public files: string[];
-  public folders: string[];
+  public tree!: string[];
+  public files!: string[];
+  public folders!: string[];

-  constructor(bucketRefArg: Bucket, parentDiretory: Directory, name: string) {
+  constructor(bucketRefArg: Bucket, parentDirectory: Directory, name: string) {
    this.bucketRef = bucketRefArg;
-    this.parentDirectoryRef = parentDiretory;
+    this.parentDirectoryRef = parentDirectory;
    this.name = name;
  }

@@ -63,52 +66,100 @@ export class Directory {
   * gets a file by name
   */
  public async getFile(optionsArg: {
-    name: string;
+    path: string;
    createWithContents?: string | Buffer;
+    getFromTrash?: boolean;
  }): Promise<File> {
-    // check wether the file exists
+    const pathDescriptor = {
+      directory: this,
+      path: optionsArg.path,
+    };
    const exists = await this.bucketRef.fastExists({
-      path: this.getBasePath() + optionsArg.name,
+      path: await helpers.reducePathDescriptorToPath(pathDescriptor),
    });
+    if (!exists && optionsArg.getFromTrash) {
+      const trash = await this.bucketRef.getTrash();
+      const trashedFile = await trash.getTrashedFileByOriginalName(pathDescriptor);
+      return trashedFile;
+    }
    if (!exists && !optionsArg.createWithContents) {
-      return null;
+      throw new Error(`File not found at path '${optionsArg.path}'`);
    }
    if (!exists && optionsArg.createWithContents) {
-      await this.fastPut({
-        path: optionsArg.name,
+      await File.create({
+        directory: this,
+        name: optionsArg.path,
        contents: optionsArg.createWithContents,
      });
    }
    return new File({
      directoryRefArg: this,
-      fileName: optionsArg.name,
-    })
+      fileName: optionsArg.path,
+    });
+  }
+
+
+  /**
+   * Check if a file exists in this directory
+   */
+  public async fileExists(optionsArg: { path: string }): Promise<boolean> {
+    const pathDescriptor = {
+      directory: this,
+      path: optionsArg.path,
+    };
+    return this.bucketRef.fastExists({
+      path: await helpers.reducePathDescriptorToPath(pathDescriptor),
+    });
+  }
+
+  /**
+   * Check if a subdirectory exists
+   */
+  public async directoryExists(dirNameArg: string): Promise<boolean> {
+    const directories = await this.listDirectories();
+    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.s3Client.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 done = plugins.smartpromise.defer();
-    const fileNameStream = await this.bucketRef.smartbucketRef.minioClient.listObjectsV2(
-      this.bucketRef.name,
-      this.getBasePath(),
-      false
-    );
+    const { contents } = await this.listObjectsV2AllPages(this.getBasePath(), '/');
    const fileArray: File[] = [];
-    const duplexStream = new plugins.smartstream.SmartDuplex<plugins.minio.BucketItem, void>({
-      objectMode: true,
-      writeFunction: async (bucketItem) => {
-        if (bucketItem.prefix) {
-          return;
-        }
-        if (!bucketItem.name) {
-          return;
-        }
-        let subtractedPath = bucketItem.name.replace(this.getBasePath(), '');
-        if (subtractedPath.startsWith('/')) {
-          subtractedPath = subtractedPath.substr(1);
-        }
+
+    contents.forEach((item) => {
+      if (item.Key && !item.Key.endsWith('/')) {
+        const subtractedPath = item.Key.replace(this.getBasePath(), '');
        if (!subtractedPath.includes('/')) {
          fileArray.push(
            new File({
@@ -117,13 +168,9 @@ export class Directory {
            })
          );
        }
-      },
-      finalFunction: async (tools) => {
-        done.resolve();
      }
    });
-    fileNameStream.pipe(duplexStream);
-    await done.promise;
+
    return fileArray;
  }

@@ -131,90 +178,136 @@ export class Directory {
   * lists all folders
   */
  public async listDirectories(): Promise<Directory[]> {
-    const done = plugins.smartpromise.defer();
-    const basePath = this.getBasePath();
-    const completeDirStream = await this.bucketRef.smartbucketRef.minioClient.listObjectsV2(
-      this.bucketRef.name,
-      this.getBasePath(),
-      false
-    );
-    const directoryArray: Directory[] = [];
-    const duplexStream = new plugins.smartstream.SmartDuplex<plugins.minio.BucketItem, void>({
-      objectMode: true,
-      writeFunction: async (bucketItem) => {
-        if (bucketItem.name) {
-          return;
-        }
-        let subtractedPath = bucketItem.prefix.replace(this.getBasePath(), '');
-        if (subtractedPath.startsWith('/')) {
-          subtractedPath = subtractedPath.substr(1);
-        }
-        if (subtractedPath.includes('/')) {
-          const dirName = subtractedPath.split('/')[0];
-          if (directoryArray.find((directory) => directory.name === dirName)) {
-            return;
+    try {
+      const { commonPrefixes } = await this.listObjectsV2AllPages(this.getBasePath(), '/');
+      const directoryArray: Directory[] = [];
+  
+      if (commonPrefixes) {
+        commonPrefixes.forEach((item) => {
+          if (item.Prefix) {
+            const subtractedPath = item.Prefix.replace(this.getBasePath(), '');
+            if (subtractedPath.endsWith('/')) {
+              const dirName = subtractedPath.slice(0, -1);
+              // Ensure the directory name is not empty (which would indicate the base directory itself)
+              if (dirName) {
+                directoryArray.push(new Directory(this.bucketRef, this, dirName));
+              }
+            }
          }
-          directoryArray.push(new Directory(this.bucketRef, this, dirName));
-        }
-      },
-      finalFunction: async (tools) => {
-        done.resolve();
+        });
      }
-    });
-    completeDirStream.pipe(duplexStream);
-    await done.promise;
-    return directoryArray;
+  
+      return directoryArray;
+    } catch (error) {
+      console.error('Error listing directories:', error);
+      throw error;
+    }
  }

  /**
-   * gets an array that has all objects with a certain prefix;
+   * gets an array that has all objects with a certain prefix
   */
  public async getTreeArray() {
-    const treeArray = await this.bucketRef.smartbucketRef.minioClient.listObjectsV2(
-      this.bucketRef.name,
-      this.getBasePath(),
-      true
-    );
+    const command = new plugins.s3.ListObjectsV2Command({
+      Bucket: this.bucketRef.name,
+      Prefix: this.getBasePath(),
+      Delimiter: '/',
+    });
+    const response = await this.bucketRef.smartbucketRef.s3Client.send(command);
+    return response.Contents;
  }

  /**
-   * gets a sub directory
+   * gets a sub directory by name
   */
-  public async getSubDirectoryByName(dirNameArg: string): Promise<Directory> {
-    const dirNameArray = dirNameArg.split('/');
+  public async getSubDirectoryByName(dirNameArg: string, optionsArg: {
+    /**
+     * in s3 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
+     * this option creates a directory even if it is empty using a initializer file
+     */
+    createWithInitializerFile?: boolean;
+    /**
+     * if the path is a file path, it will be treated as a file and the parent directory will be returned
+     */
+    couldBeFilePath?: boolean;
+  } = {}): Promise<Directory> {

-    const getDirectory = async (directoryArg: Directory, dirNameToSearch: string) => {
+    const dirNameArray = dirNameArg.split('/').filter(str => str.trim() !== "");
+
+    optionsArg = {
+      getEmptyDirectory: false,
+      createWithInitializerFile: false,
+      ...optionsArg,
+    }
+
+
+    const getDirectory = async (directoryArg: Directory, dirNameToSearch: string, isFinalDirectory: boolean) => {
      const directories = await directoryArg.listDirectories();
-      return directories.find((directory) => {
+      let returnDirectory = directories.find((directory) => {
        return directory.name === dirNameToSearch;
      });
+      if (returnDirectory) {
+        return returnDirectory;
+      }
+      if (optionsArg.getEmptyDirectory || optionsArg.createWithInitializerFile) {
+        returnDirectory = new Directory(this.bucketRef, directoryArg, dirNameToSearch);
+      }
+      if (isFinalDirectory && optionsArg.createWithInitializerFile) {
+        returnDirectory?.createEmptyFile('00init.txt');
+      }
+      return returnDirectory || null;
    };
-    let wantedDirectory: Directory;
+
+    if (optionsArg.couldBeFilePath) {
+      const baseDirectory = await this.bucketRef.getBaseDirectory();
+      const existingFile = await baseDirectory.getFile({
+        path: dirNameArg,
+      });
+      if (existingFile) {
+        const adjustedPath = dirNameArg.substring(0, dirNameArg.lastIndexOf('/'));
+        return this.getSubDirectoryByName(adjustedPath);
+      }
+    }
+
+    let wantedDirectory: Directory | null = null;
+    let counter = 0;
    for (const dirNameToSearch of dirNameArray) {
+      counter++;
      const directoryToSearchIn = wantedDirectory ? wantedDirectory : this;
-      wantedDirectory = await getDirectory(directoryToSearchIn, dirNameToSearch);
+      wantedDirectory = await getDirectory(directoryToSearchIn, dirNameToSearch, counter === dirNameArray.length);
+    }
+
+    if (!wantedDirectory) {
+      throw new Error(`Directory not found at path '${dirNameArg}'`);
    }
    return wantedDirectory;
  }

+
  /**
   * moves the directory
   */
  public async move() {
    // TODO
-    throw new Error('moving a directory is not yet implemented');
+    throw new Error('Moving a directory is not yet implemented');
  }

  /**
-   * creates a file within this directory
+   * creates an empty file within this directory
   * @param relativePathArg
   */
  public async createEmptyFile(relativePathArg: string) {
-    const emtpyFile = await File.create({
+    const emptyFile = await File.create({
      directory: this,
      name: relativePathArg,
      contents: '',
    });
+    return emptyFile;
  }

  // file operations
@@ -234,29 +327,82 @@ export class Directory {
    return result;
  }

-  public async fastGetStream(pathArg: string): Promise<plugins.smartrx.rxjs.ReplaySubject<Buffer>> {
-    const path = plugins.path.join(this.getBasePath(), pathArg);
-    const result = await this.bucketRef.fastGetStream({
-      path,
-    });
+  public fastGetStream(
+    optionsArg: {
+      path: string;
+    },
+    typeArg: 'webstream'
+  ): Promise<ReadableStream>;
+  public async fastGetStream(
+    optionsArg: {
+      path: string;
+    },
+    typeArg: 'nodestream'
+  ): Promise<plugins.stream.Readable>;
+
+  /**
+   * fastGetStream
+   * @param optionsArg
+   * @returns
+   */
+  public async fastGetStream(
+    optionsArg: { path: string },
+    typeArg: 'webstream' | 'nodestream'
+  ): Promise<ReadableStream | plugins.stream.Readable> {
+    const path = plugins.path.join(this.getBasePath(), optionsArg.path);
+    const result = await this.bucketRef.fastGetStream(
+      {
+        path,
+      },
+      typeArg as any
+    );
    return result;
  }

-  public async fastRemove(optionsArg: { path: string }) {
+  /**
+   * fast put stream
+   */
+  public async fastPutStream(optionsArg: {
+    path: string;
+    stream: plugins.stream.Readable;
+  }): Promise<void> {
    const path = plugins.path.join(this.getBasePath(), optionsArg.path);
-    await this.bucketRef.fastRemove({
+    await this.bucketRef.fastPutStream({
      path,
+      readableStream: optionsArg.stream,
+    });
+  }
+
+  /**
+   * removes a file within the directory
+   * uses file class to make sure effects for metadata etc. are handled correctly
+   * @param optionsArg
+   */
+  public async fastRemove(optionsArg: {
+    path: string
+    /**
+     * wether the file should be placed into trash. Default is false.
+     */
+    mode?: 'permanent' | 'trash';
+  }) {
+    const file = await this.getFile({
+      path: optionsArg.path,
+    });
+    await file.delete({
+      mode: optionsArg.mode ? optionsArg.mode : 'permanent',
    });
  }

  /**
   * deletes the directory with all its contents
   */
-  public async delete() {
+  public async delete(optionsArg: {
+    mode?: 'permanent' | 'trash';
+  }) {
    const deleteDirectory = async (directoryArg: Directory) => {
      const childDirectories = await directoryArg.listDirectories();
      if (childDirectories.length === 0) {
-        console.log('directory empty! Path complete!');
+        console.log('Directory empty! Path complete!');
      } else {
        for (const childDir of childDirectories) {
          await deleteDirectory(childDir);
@@ -264,9 +410,9 @@ export class Directory {
      }
      const files = await directoryArg.listFiles();
      for (const file of files) {
-        await directoryArg.fastRemove({
-          path: file.name,
-        });
+        await file.delete({
+          mode: optionsArg.mode ? optionsArg.mode : 'permanent',
+        })
      }
    };
    await deleteDirectory(this);
--- a/ts/classes.file.ts
+++ b/ts/classes.file.ts
@@ -1,8 +1,9 @@
 import * as plugins from './plugins.js';
+import * as helpers from './helpers.js';
+import * as interfaces from './interfaces.js';
 import { Directory } from './classes.directory.js';
 import { MetaData } from './classes.metadata.js';

-
 /**
 * represents a file in a directory
 */
@@ -31,7 +32,12 @@ export class File {
      directoryRefArg: optionsArg.directory,
      fileName: optionsArg.name,
    });
-    if (contents instanceof plugins.stream.Readable) {} else {
+    if (contents instanceof plugins.stream.Readable) {
+      await optionsArg.directory.fastPutStream({
+        path: optionsArg.name,
+        stream: contents,
+      });
+    } else {
      await optionsArg.directory.fastPut({
        path: optionsArg.name,
        contents: contents,
@@ -44,9 +50,13 @@ export class File {
  public parentDirectoryRef: Directory;
  public name: string;

+  /**
+   * get the full path to the file
+   * @returns the full path to the file
+   */
  public getBasePath(): string {
    return plugins.path.join(this.parentDirectoryRef.getBasePath(), this.name);
-  };
+  }

  constructor(optionsArg: { directoryRefArg: Directory; fileName: string }) {
    this.parentDirectoryRef = optionsArg.directoryRefArg;
@@ -65,33 +75,86 @@ export class File {
    return resultBuffer;
  }

-  public async getReadStream() {
-    const readStream = this.parentDirectoryRef.bucketRef.fastGetStream({
-      path: this.getBasePath(),
-    });
+  public async getReadStream(typeArg: 'webstream'): Promise<ReadableStream>;
+  public async getReadStream(typeArg: 'nodestream'): Promise<plugins.stream.Readable>;
+  public async getReadStream(
+    typeArg: 'nodestream' | 'webstream'
+  ): Promise<ReadableStream | plugins.stream.Readable> {
+    const readStream = this.parentDirectoryRef.bucketRef.fastGetStream(
+      {
+        path: this.getBasePath(),
+      },
+      typeArg as any
+    );
+    return readStream;
  }

  /**
-   * removes this file
-   * for using recycling mechanics use .delete()
+   * deletes this file
   */
-  public async remove() {
-    await this.parentDirectoryRef.bucketRef.fastRemove({
-      path: this.getBasePath(),
-    });
-    if (!this.name.endsWith('.metadata')) {
+  public async delete(optionsArg?: { mode: 'trash' | 'permanent' }) {
+    optionsArg = {
+      ...{
+        mode: 'permanent',
+      },
+      ...optionsArg,
+    };
+
+    if (optionsArg.mode === 'permanent') {
      await this.parentDirectoryRef.bucketRef.fastRemove({
-        path: this.getBasePath() + '.metadata',
+        path: this.getBasePath(),
+      });
+      if (!this.name.endsWith('.metadata')) {
+        if (await this.hasMetaData()) {
+          const metadata = await this.getMetaData();
+          await metadata.metadataFile.delete(optionsArg);
+        }
+      }
+    } else if (optionsArg.mode === 'trash') {
+      const metadata = await this.getMetaData();
+      await metadata.storeCustomMetaData({
+        key: 'recycle',
+        value: {
+          deletedAt: Date.now(),
+          originalPath: this.getBasePath(),
+        },
+      });
+      const trash = await this.parentDirectoryRef.bucketRef.getTrash();
+      const trashDir = await trash.getTrashDir();
+      await this.move({
+        directory: trashDir,
+        path: await trash.getTrashKeyByOriginalBasePath(this.getBasePath()),
      });
    }
+
    await this.parentDirectoryRef.listFiles();
  }

  /**
-   * deletes the file with recycling mechanics
+   * restores
   */
-  public async delete() {
-    await this.remove();
+  public async restore(optionsArg: {
+    useOriginalPath?: boolean;
+    toPath?: string;
+    overwrite?: boolean;
+  } = {}) {
+    optionsArg = {
+      useOriginalPath: (() => {
+        return optionsArg.toPath ? false : true;
+      })(),
+      overwrite: false,
+      ...optionsArg,
+    };
+    const metadata = await this.getMetaData();
+    const moveToPath = optionsArg.toPath || (await metadata.getCustomMetaData({
+      key: 'recycle'
+    })).originalPath;
+    await metadata.deleteCustomMetaData({
+      key: 'recycle'
+    })
+    await this.move({
+      path: moveToPath,
+    });
  }

  /**
@@ -118,32 +181,90 @@ export class File {
  }) {
    const metadata = await this.getMetaData();
    await metadata.removeLock({
-      force: optionsArg?.force,
+      force: optionsArg?.force || false,
    });
  }

  public async updateWithContents(optionsArg: {
-    contents: Buffer | string | plugins.stream.Readable;
+    contents: Buffer | string | plugins.stream.Readable | ReadableStream;
    encoding?: 'utf8' | 'binary';
  }) {
-    if (optionsArg.contents instanceof plugins.stream.Readable) {
+    if (
+      optionsArg.contents instanceof plugins.stream.Readable ||
+      optionsArg.contents instanceof ReadableStream
+    ) {
      await this.parentDirectoryRef.bucketRef.fastPutStream({
        path: this.getBasePath(),
-        dataStream: optionsArg.contents,
+        readableStream: optionsArg.contents,
+        overwrite: true,
      });
    } else if (Buffer.isBuffer(optionsArg.contents)) {
      await this.parentDirectoryRef.bucketRef.fastPut({
        path: this.getBasePath(),
        contents: optionsArg.contents,
+        overwrite: true,
      });
    } else if (typeof optionsArg.contents === 'string') {
      await this.parentDirectoryRef.bucketRef.fastPut({
        path: this.getBasePath(),
        contents: Buffer.from(optionsArg.contents, optionsArg.encoding),
+        overwrite: true,
      });
    }
  }

+  /**
+   * moves the file to another directory
+   */
+  public async move(pathDescriptorArg: interfaces.IPathDecriptor) {
+    let moveToPath: string = '';
+    const isDirectory = await this.parentDirectoryRef.bucketRef.isDirectory(pathDescriptorArg);
+    if (isDirectory) {
+      moveToPath = await helpers.reducePathDescriptorToPath({
+        ...pathDescriptorArg,
+        path: plugins.path.join(pathDescriptorArg.path!, this.name),
+      });
+    } else {
+      moveToPath = await helpers.reducePathDescriptorToPath(pathDescriptorArg);
+    }
+    // lets move the file
+    await this.parentDirectoryRef.bucketRef.fastMove({
+      sourcePath: this.getBasePath(),
+      destinationPath: moveToPath,
+      overwrite: true,
+    });
+    // lets move the metadatafile
+    if (!this.name.endsWith('.metadata')) {
+      const metadata = await this.getMetaData();
+      await this.parentDirectoryRef.bucketRef.fastMove({
+        sourcePath: metadata.metadataFile.getBasePath(),
+        destinationPath: moveToPath + '.metadata',
+        overwrite: true,
+      });
+    }
+
+    // lets update references of this
+    const baseDirectory = await this.parentDirectoryRef.bucketRef.getBaseDirectory();
+    this.parentDirectoryRef = await baseDirectory.getSubDirectoryByName(
+      await helpers.reducePathDescriptorToPath(pathDescriptorArg),
+      {
+        couldBeFilePath: true,
+      }
+    );
+    this.name = pathDescriptorArg.path!;
+  }
+
+  public async hasMetaData(): Promise<boolean> {
+    if (!this.name.endsWith('.metadata')) {
+      const hasMetadataBool = MetaData.hasMetaData({
+        file: this,
+      });
+      return hasMetadataBool;
+    } else {
+      return false;
+    }
+  }
+
  /**
   * allows updating the metadata of a file
   * @param updatedMetadata
@@ -172,4 +293,11 @@ export class File {
      contents: JSON.stringify(dataArg),
    });
  }
+
+  public async getMagicBytes(optionsArg: { length: number }): Promise<Buffer> {
+    return this.parentDirectoryRef.bucketRef.getMagicBytes({
+      path: this.getBasePath(),
+      length: optionsArg.length,
+    });
+  }
 }
--- 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.s3Client.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
@@ -3,6 +3,26 @@ import * as plugins from './plugins.js';
 import { File } from './classes.file.js';

 export class MetaData {
+  public static async hasMetaData(optionsArg: { file: File }) {
+    // try finding the existing metadata file; return false if it doesn't exist
+    try {
+      const existingFile = await optionsArg.file.parentDirectoryRef.getFile({
+        path: optionsArg.file.name + '.metadata',
+      });
+      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
  public static async createForFile(optionsArg: { file: File }) {
    const metaData = new MetaData();
@@ -10,7 +30,7 @@ export class MetaData {

    // lets find the existing metadata file
    metaData.metadataFile = await metaData.fileRef.parentDirectoryRef.getFile({
-      name: metaData.fileRef.name + '.metadata',
+      path: metaData.fileRef.name + '.metadata',
      createWithContents: '{}',
    });

@@ -21,20 +41,34 @@ export class MetaData {
  /**
   * the file that contains the metadata
   */
-  metadataFile: File;
+  metadataFile!: File;

  /**
   * the file that the metadata is for
   */
-  fileRef: File;
+  fileRef!: File;

  public async getFileType(optionsArg?: {
    useFileExtension?: boolean;
    useMagicBytes?: boolean;
-  }): Promise<string> {
-    if ((optionsArg && optionsArg.useFileExtension) || optionsArg.useFileExtension === undefined) {
-      return plugins.path.extname(this.fileRef.name);
+  }): Promise<plugins.smartmime.IFileTypeResult | undefined> {
+    if ((optionsArg && optionsArg.useFileExtension) || !optionsArg) {
+      const fileType = await plugins.smartmime.detectMimeType({
+        path: this.fileRef.name,
+      });
+
+      return fileType;
    }
+    if (optionsArg && optionsArg.useMagicBytes) {
+      const fileType = await plugins.smartmime.detectMimeType({
+        buffer: await this.fileRef.getMagicBytes({
+          length: 100,
+        })
+      });
+
+      return fileType;
+    }
+    throw new Error('optionsArg.useFileExtension and optionsArg.useMagicBytes cannot both be false');
  }

  /**
@@ -44,13 +78,13 @@ export class MetaData {
    const stat = await this.fileRef.parentDirectoryRef.bucketRef.fastStat({
      path: this.fileRef.getBasePath(),
    });
-    return stat.size;
+    return stat.ContentLength!;
  }

  private prefixCustomMetaData = 'custom_';

  public async storeCustomMetaData<T = any>(optionsArg: { key: string; value: T }) {
-    const data = await this.metadataFile.getContentsAsString();
+    const data = await this.metadataFile.getJsonData();
    data[this.prefixCustomMetaData + optionsArg.key] = optionsArg.value;
    await this.metadataFile.writeJsonData(data);
  }
--- a/ts/classes.smartbucket.ts
+++ b/ts/classes.smartbucket.ts
@@ -1,22 +1,31 @@
+// classes.smartbucket.ts
+
 import * as plugins from './plugins.js';
 import { Bucket } from './classes.bucket.js';
+import { normalizeS3Descriptor } from './helpers.js';

 export class SmartBucket {
  public config: plugins.tsclass.storage.IS3Descriptor;

-  public minioClient: plugins.minio.Client;
+  public s3Client: plugins.s3.S3Client;

+  /**
+   * the constructor of SmartBucket
+   */
  /**
   * the constructor of SmartBucket
   */
  constructor(configArg: plugins.tsclass.storage.IS3Descriptor) {
    this.config = configArg;
-    this.minioClient = new plugins.minio.Client({
-      endPoint: this.config.endpoint,
-      port: configArg.port || 443,
-      useSSL: configArg.useSsl !== undefined ? configArg.useSsl : true,
-      accessKey: this.config.accessKey,
-      secretKey: this.config.accessSecret,
+
+    // Use the normalizer to handle various endpoint formats
+    const { normalized } = normalizeS3Descriptor(configArg);
+
+    this.s3Client = new plugins.s3.S3Client({
+      endpoint: normalized.endpointUrl,
+      region: normalized.region,
+      credentials: normalized.credentials,
+      forcePathStyle: normalized.forcePathStyle, // Necessary for S3-compatible storage like MinIO or Wasabi
    });
  }

@@ -29,7 +38,16 @@ export class SmartBucket {
    await Bucket.removeBucketByName(this, bucketName);
  }

-  public async getBucketByName(bucketName: string) {
-    return Bucket.getBucketByName(this, bucketName);
+  public async getBucketByName(bucketNameArg: string) {
+    return Bucket.getBucketByName(this, bucketNameArg);
+  }
+
+  /**
+   * Check if a bucket exists
+   */
+  public async bucketExists(bucketNameArg: string): Promise<boolean> {
+    const command = new plugins.s3.ListBucketsCommand({});
+    const buckets = await this.s3Client.send(command);
+    return buckets.Buckets?.some(bucket => bucket.Name === bucketNameArg) ?? false;
  }
 }
--- a/ts/classes.trash.ts
+++ b/ts/classes.trash.ts
@@ -0,0 +1,30 @@
+import * as plugins from './plugins.js';
+import * as interfaces from './interfaces.js';
+import * as helpers from './helpers.js';
+import type { Bucket } from './classes.bucket.js';
+import type { Directory } from './classes.directory.js';
+import type { File } from './classes.file.js';
+
+
+export class Trash {
+  public bucketRef: Bucket;
+
+  constructor(bucketRefArg: Bucket) {
+    this.bucketRef = bucketRefArg;
+  }
+
+  public async getTrashDir() {
+    return this.bucketRef.getDirectoryFromPath({ path: '.trash' });
+  }
+
+  public async getTrashedFileByOriginalName(pathDescriptor: interfaces.IPathDecriptor): Promise<File> {
+    const trashDir = await this.getTrashDir();
+    const originalPath = await helpers.reducePathDescriptorToPath(pathDescriptor);
+    const trashKey = await this.getTrashKeyByOriginalBasePath(originalPath);
+    return trashDir.getFile({ path: trashKey });
+  }
+
+  public async getTrashKeyByOriginalBasePath (originalPath: string): Promise<string> {
+    return plugins.smartstring.base64.encode(originalPath);
+  }
+}
--- a/ts/helpers.ts
+++ b/ts/helpers.ts
@@ -0,0 +1,254 @@
+import * as plugins from './plugins.js';
+import * as interfaces from './interfaces.js';
+
+export const reducePathDescriptorToPath = async (pathDescriptorArg: interfaces.IPathDecriptor): Promise<string> => {
+  let returnPath = ``
+  if (pathDescriptorArg.directory) {
+    if (pathDescriptorArg.path && plugins.path.isAbsolute(pathDescriptorArg.path)) {
+      console.warn('Directory is being ignored when path is absolute.');
+      returnPath = pathDescriptorArg.path;
+    } else if (pathDescriptorArg.path) {
+      returnPath = plugins.path.join(pathDescriptorArg.directory.getBasePath(), pathDescriptorArg.path);
+    }
+  } else if (pathDescriptorArg.path) {
+    returnPath = pathDescriptorArg.path;
+  } else {
+    throw new Error('You must specify either a path or a directory.');
+  }
+  if (returnPath.startsWith('/')) {
+    returnPath = returnPath.substring(1);
+  }
+  return returnPath;
+}
+
+// S3 Descriptor Normalization
+export interface IS3Warning {
+  code: string;
+  message: string;
+}
+
+export interface INormalizedS3Config {
+  endpointUrl: string;
+  host: string;
+  protocol: 'http' | 'https';
+  port?: number;
+  region: string;
+  credentials: {
+    accessKeyId: string;
+    secretAccessKey: string;
+  };
+  forcePathStyle: boolean;
+}
+
+function coerceBooleanMaybe(value: unknown): { value: boolean | undefined; warning?: IS3Warning } {
+  if (typeof value === 'boolean') return { value };
+  if (typeof value === 'string') {
+    const v = value.trim().toLowerCase();
+    if (v === 'true' || v === '1') {
+      return { 
+        value: true, 
+        warning: { 
+          code: 'SBK_S3_COERCED_USESSL', 
+          message: `Coerced useSsl='${value}' (string) to boolean true.` 
+        } 
+      };
+    }
+    if (v === 'false' || v === '0') {
+      return { 
+        value: false, 
+        warning: { 
+          code: 'SBK_S3_COERCED_USESSL', 
+          message: `Coerced useSsl='${value}' (string) to boolean false.` 
+        } 
+      };
+    }
+  }
+  return { value: undefined };
+}
+
+function coercePortMaybe(port: unknown): { value: number | undefined; warning?: IS3Warning } {
+  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) {
+    return { 
+      value: undefined, 
+      warning: { 
+        code: 'SBK_S3_INVALID_PORT', 
+        message: `Invalid port '${String(port)}' - expected integer in [1..65535].` 
+      } 
+    };
+  }
+  return { value: n };
+}
+
+function sanitizeEndpointString(raw: unknown): { value: string; warnings: IS3Warning[] } {
+  const warnings: IS3Warning[] = [];
+  let s = String(raw ?? '').trim();
+  if (s !== String(raw ?? '')) {
+    warnings.push({ 
+      code: 'SBK_S3_TRIMMED_ENDPOINT', 
+      message: 'Trimmed surrounding whitespace from endpoint.' 
+    });
+  }
+  return { value: s, warnings };
+}
+
+function parseEndpointHostPort(
+  endpoint: string, 
+  provisionalProtocol: 'http' | 'https'
+): { 
+  hadScheme: boolean; 
+  host: string; 
+  port?: number; 
+  extras: { 
+    droppedPath?: boolean; 
+    droppedQuery?: boolean; 
+    droppedCreds?: boolean 
+  } 
+} {
+  let url: URL | undefined;
+  const extras: { droppedPath?: boolean; droppedQuery?: boolean; droppedCreds?: boolean } = {};
+  
+  // Check if endpoint already has a scheme
+  const hasScheme = /^https?:\/\//i.test(endpoint);
+  
+  // Try parsing as full URL first
+  try {
+    if (hasScheme) {
+      url = new URL(endpoint);
+    } else {
+      // Not a full URL; try host[:port] by attaching provisional scheme
+      // Remove anything after first '/' for safety
+      const cleanEndpoint = endpoint.replace(/\/.*/, '');
+      url = new URL(`${provisionalProtocol}://${cleanEndpoint}`);
+    }
+  } catch (e) {
+    throw new Error(`Unable to parse endpoint '${endpoint}'.`);
+  }
+  
+  // Check for dropped components
+  if (url.username || url.password) extras.droppedCreds = true;
+  if (url.pathname && url.pathname !== '/') extras.droppedPath = true;
+  if (url.search) extras.droppedQuery = true;
+
+  const hadScheme = hasScheme;
+  const host = url.hostname; // hostnames lowercased by URL; IPs preserved
+  const port = url.port ? Number(url.port) : undefined;
+
+  return { hadScheme, host, port, extras };
+}
+
+export function normalizeS3Descriptor(
+  input: plugins.tsclass.storage.IS3Descriptor,
+  logger?: { warn: (msg: string) => void }
+): { normalized: INormalizedS3Config; warnings: IS3Warning[] } {
+  const warnings: IS3Warning[] = [];
+  const logWarn = (w: IS3Warning) => { 
+    warnings.push(w); 
+    if (logger) {
+      logger.warn(`[SmartBucket S3] ${w.code}: ${w.message}`);
+    } else {
+      console.warn(`[SmartBucket S3] ${w.code}: ${w.message}`);
+    }
+  };
+
+  // Coerce and sanitize inputs
+  const { value: coercedUseSsl, warning: useSslWarn } = coerceBooleanMaybe((input as any).useSsl);
+  if (useSslWarn) logWarn(useSslWarn);
+  
+  const { value: coercedPort, warning: portWarn } = coercePortMaybe((input as any).port);
+  if (portWarn) logWarn(portWarn);
+
+  const { value: endpointStr, warnings: endpointSanWarnings } = sanitizeEndpointString((input as any).endpoint);
+  endpointSanWarnings.forEach(logWarn);
+
+  if (!endpointStr) {
+    throw new Error('S3 endpoint is required (got empty string). Provide hostname or URL.');
+  }
+
+  // Provisional protocol selection for parsing host:port forms
+  const provisionalProtocol: 'http' | 'https' = coercedUseSsl === false ? 'http' : 'https';
+
+  const { hadScheme, host, port: epPort, extras } = parseEndpointHostPort(endpointStr, provisionalProtocol);
+
+  if (extras.droppedCreds) {
+    logWarn({ 
+      code: 'SBK_S3_DROPPED_CREDENTIALS', 
+      message: 'Ignored credentials in endpoint URL.' 
+    });
+  }
+  if (extras.droppedPath) {
+    logWarn({ 
+      code: 'SBK_S3_DROPPED_PATH', 
+      message: 'Removed path segment from endpoint URL; S3 endpoint should be host[:port] only.' 
+    });
+  }
+  if (extras.droppedQuery) {
+    logWarn({ 
+      code: 'SBK_S3_DROPPED_QUERY', 
+      message: 'Removed query string from endpoint URL; S3 endpoint should be host[:port] only.' 
+    });
+  }
+
+  // Final protocol decision
+  let finalProtocol: 'http' | 'https';
+  if (hadScheme) {
+    // Scheme from endpoint wins
+    const schemeFromEndpoint = endpointStr.trim().toLowerCase().startsWith('http://') ? 'http' : 'https';
+    finalProtocol = schemeFromEndpoint;
+    if (typeof coercedUseSsl === 'boolean') {
+      const expected = coercedUseSsl ? 'https' : 'http';
+      if (expected !== finalProtocol) {
+        logWarn({ 
+          code: 'SBK_S3_SCHEME_CONFLICT', 
+          message: `useSsl=${String(coercedUseSsl)} conflicts with endpoint scheme '${finalProtocol}'; using endpoint scheme.` 
+        });
+      }
+    }
+  } else {
+    if (typeof coercedUseSsl === 'boolean') {
+      finalProtocol = coercedUseSsl ? 'https' : 'http';
+    } else {
+      finalProtocol = 'https';
+      logWarn({ 
+        code: 'SBK_S3_GUESSED_PROTOCOL', 
+        message: "No scheme in endpoint and useSsl not provided; defaulting to 'https'." 
+      });
+    }
+  }
+
+  // Final port decision
+  let finalPort: number | undefined = undefined;
+  if (coercedPort !== undefined && epPort !== undefined && coercedPort !== epPort) {
+    logWarn({ 
+      code: 'SBK_S3_PORT_CONFLICT', 
+      message: `Port in config (${coercedPort}) conflicts with endpoint port (${epPort}); using config port.` 
+    });
+    finalPort = coercedPort;
+  } else {
+    finalPort = (coercedPort !== undefined) ? coercedPort : epPort;
+  }
+
+  // Build canonical endpoint URL (origin only, no trailing slash)
+  const url = new URL(`${finalProtocol}://${host}`);
+  if (finalPort !== undefined) url.port = String(finalPort);
+  const endpointUrl = url.origin;
+
+  const region = input.region || 'us-east-1';
+
+  return {
+    normalized: {
+      endpointUrl,
+      host,
+      protocol: finalProtocol,
+      port: finalPort,
+      region,
+      credentials: {
+        accessKeyId: input.accessKey,
+        secretAccessKey: input.accessSecret,
+      },
+      forcePathStyle: true,
+    },
+    warnings,
+  };
+}
--- a/ts/index.ts
+++ b/ts/index.ts
@@ -2,3 +2,6 @@ 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';
--- a/ts/interfaces.ts
+++ b/ts/interfaces.ts
@@ -0,0 +1,6 @@
+import type { Directory } from "./classes.directory.js";
+
+export interface IPathDecriptor {
+  path?: string;
+  directory?: Directory;
+}
--- a/ts/plugins.ts
+++ b/ts/plugins.ts
@@ -1,6 +1,8 @@
+// plugins.ts
+
 // node native
-import * as path from 'path';
-import * as stream from 'stream';
+import * as path from 'node:path';
+import * as stream from 'node:stream';

 export { path, stream };

@@ -10,8 +12,10 @@ import * as smartpath from '@push.rocks/smartpath';
 import * as smartpromise from '@push.rocks/smartpromise';
 import * as smartrx from '@push.rocks/smartrx';
 import * as smartstream from '@push.rocks/smartstream';
+import * as smartstring from '@push.rocks/smartstring';
+import * as smartunique from '@push.rocks/smartunique';

-export { smartmime, smartpath, smartpromise, smartrx, smartstream };
+export { smartmime, smartpath, smartpromise, smartrx, smartstream, smartstring, smartunique };

 // @tsclass
 import * as tsclass from '@tsclass/tsclass';
@@ -21,6 +25,10 @@ export {
 }

 // third party scope
-import * as minio from 'minio';
+import * as s3 from '@aws-sdk/client-s3';
+import { Minimatch } from 'minimatch';

-export { minio };
+export {
+  s3,
+  Minimatch,
+}
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -6,7 +6,8 @@
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "esModuleInterop": true,
-    "verbatimModuleSyntax": true
+    "verbatimModuleSyntax": true,
+    "strict": true
  },
  "exclude": [
    "dist_*/**/*.d.ts"
Author	SHA1	Message	Date
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
Juergen Kunz	e147a077f3	v4.0.0	2025-11-20 13:20:19 +00:00
Juergen Kunz	5889396134	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	2025-11-20 13:20:19 +00:00
Juergen Kunz	0c631383e1	3.3.10	2025-08-18 02:43:29 +00:00
Juergen Kunz	d852d8c85b	fix(helpers): Normalize and robustly parse S3 endpoint configuration; use normalized descriptor in SmartBucket and update dev tooling	2025-08-18 02:43:29 +00:00
Juergen Kunz	fa4c44ae04	3.3.9	2025-08-15 18:31:42 +00:00
Juergen Kunz	708b0b63b1	fix(docs): Revise README with detailed usage examples and add local Claude settings	2025-08-15 18:31:42 +00:00
Juergen Kunz	8554554642	3.3.8	2025-08-15 18:28:27 +00:00
Juergen Kunz	a04aabf78b	fix(tests): Update tests to use @git.zone/tstest, upgrade dependencies, remove GitLab CI and add local CI/workspace config	2025-08-15 18:28:27 +00:00
Philipp Kunz	47cf2cc2cb	3.3.7	2024-12-02 17:00:42 +01:00
Philipp Kunz	ef20e15d20	fix(package): Update author field in package.json	2024-12-02 17:00:42 +01:00
Philipp Kunz	39a4bd6ab7	3.3.6	2024-12-02 17:00:17 +01:00
Philipp Kunz	c2a30654c5	fix(package): Fix license field in package.json to reflect MIT licensing	2024-12-02 17:00:17 +01:00
Philipp Kunz	8085033de4	3.3.5	2024-11-25 17:43:01 +01:00
Philipp Kunz	75dd1d43a9	fix(test): Refactor trash test to improve metadata and deletion validation	2024-11-25 17:43:00 +01:00
Philipp Kunz	8ba7cdc873	3.3.4	2024-11-25 17:36:14 +01:00
Philipp Kunz	ed8db4536b	fix(core): Minor refactoring and cleanup of TypeScript source files for improved readability and maintainability.	2024-11-25 17:36:14 +01:00
Philipp Kunz	96e3eadb31	3.3.3	2024-11-24 20:12:21 +01:00
Philipp Kunz	e9426b9cc9	fix(documentation): Improved documentation accuracy and consistency	2024-11-24 20:12:20 +01:00
Philipp Kunz	9801e15c32	3.3.2	2024-11-24 20:02:41 +01:00
Philipp Kunz	cbfdd8e123	fix(documentation): Updated keywords and description for clarity and consistency.	2024-11-24 20:02:40 +01:00
Philipp Kunz	138c38ee30	3.3.1	2024-11-24 19:59:37 +01:00
Philipp Kunz	a1e449cf94	fix(File): Fixed issue with file restore metadata operations.	2024-11-24 19:59:37 +01:00
Philipp Kunz	aa9a2e9220	3.3.0	2024-11-24 19:56:13 +01:00
Philipp Kunz	154854dc21	feat(core): Enhanced directory handling and file restoration from trash	2024-11-24 19:56:12 +01:00
Philipp Kunz	8e9041fbbf	3.2.2	2024-11-24 03:05:10 +01:00
Philipp Kunz	16a82ac50a	fix(core): Refactor Bucket class for improved error handling	2024-11-24 03:05:10 +01:00
Philipp Kunz	0b396f19cf	3.2.1	2024-11-24 02:28:48 +01:00
Philipp Kunz	6ab77ece6e	fix(metadata): Fix metadata handling for deleted files	2024-11-24 02:28:48 +01:00
Philipp Kunz	b7a1f2087c	Merge pull request 'fix: use overwrite to make metadata files work' (#2 ) from fix/smartbucket-trash into master Reviewed-on: #2	2024-11-24 01:27:58 +00:00
Philipp Kunz	b0d41fa9a0	3.2.0	2024-11-24 02:25:08 +01:00
Philipp Kunz	34082c38a7	feat(bucket): Enhanced SmartBucket with trash management and metadata handling	2024-11-24 02:25:08 +01:00
Dominik Schwank	8d160cefb0	fix: use overwrite to make metadata files work During a delete the metadata file is updated. As the overwrite property was not set, the metadata couldn't be updated and caused issues.	2024-11-18 21:08:39 +00:00
Philipp Kunz	cec9c07b7c	3.1.0	2024-11-18 15:07:47 +01:00
Philipp Kunz	383a5204f4	feat(file): Added functionality to retrieve magic bytes from files and detect file types using magic bytes.	2024-11-18 15:07:46 +01:00
Philipp Kunz	c7f0c97341	3.0.24	2024-11-18 11:24:11 +01:00
Philipp Kunz	e7f60465ff	fix(metadata): Fix metadata handling to address type assertion and data retrieval.	2024-11-18 11:24:11 +01:00
Philipp Kunz	7db4d24817	3.0.23	2024-10-16 10:27:27 +02:00
Philipp Kunz	dc599585b8	fix(dependencies): Update package dependencies for improved functionality and security.	2024-10-16 10:27:27 +02:00
Philipp Kunz	a22e32cd32	3.0.22	2024-07-28 12:46:39 +02:00
Philipp Kunz	4647181807	fix(dependencies): Update dependencies and improve bucket retrieval logging	2024-07-28 12:46:39 +02:00
Philipp Kunz	99c3935d0c	3.0.21	2024-07-04 18:39:28 +02:00
Philipp Kunz	05523dc7a1	fix(test): Update endpoint configuration in tests to use environment variable	2024-07-04 18:39:27 +02:00
Philipp Kunz	dc99cfa229	3.0.20	2024-06-19 18:28:53 +02:00
Philipp Kunz	23f8dc55d0	fix(core): update	2024-06-19 18:28:52 +02:00
Philipp Kunz	ffaf0fc97a	3.0.19	2024-06-18 18:44:59 +02:00
Philipp Kunz	2a0425ff54	fix(delete functions): ensure more consistency between methods and trash behaviour	2024-06-18 18:44:58 +02:00
Philipp Kunz	9adcdee0a0	3.0.18	2024-06-17 20:00:58 +02:00
Philipp Kunz	786f8d4365	fix(core): update	2024-06-17 20:00:57 +02:00
Philipp Kunz	67244ba5cf	3.0.17	2024-06-17 19:57:56 +02:00
Philipp Kunz	a9bb31c2a2	fix(core): update	2024-06-17 19:57:56 +02:00
Philipp Kunz	bd8b05920f	3.0.16	2024-06-17 16:01:36 +02:00
Philipp Kunz	535d9f8520	fix(core): update	2024-06-17 16:01:35 +02:00
Philipp Kunz	8401fe1c0c	3.0.15	2024-06-11 17:21:22 +02:00
Philipp Kunz	08c3f674bf	fix(core): update	2024-06-11 17:21:22 +02:00
Philipp Kunz	df0a439def	3.0.14	2024-06-11 17:20:49 +02:00
Philipp Kunz	7245b49c31	fix(core): update	2024-06-11 17:20:48 +02:00
Philipp Kunz	4b70edb947	finish trash	2024-06-10 16:47:20 +02:00
Philipp Kunz	9629a04da6	3.0.13	2024-06-09 16:32:33 +02:00
Philipp Kunz	963463d40d	fix(core): update	2024-06-09 16:32:32 +02:00
Philipp Kunz	ce58b99fc7	3.0.12	2024-06-09 16:02:34 +02:00
Philipp Kunz	591c99736d	fix(core): update	2024-06-09 16:02:33 +02:00
Philipp Kunz	559e3da47b	3.0.11	2024-06-08 19:13:25 +02:00
Philipp Kunz	a7ac870e05	fix(core): update	2024-06-08 19:13:24 +02:00
Philipp Kunz	d48c5e229a	3.0.10	2024-06-03 21:35:08 +02:00
Philipp Kunz	b9c384dd08	fix(core): update	2024-06-03 21:35:08 +02:00
Philipp Kunz	91c04b2364	update description	2024-05-29 14:11:54 +02:00
Philipp Kunz	b5dcc131e2	3.0.9	2024-05-27 17:34:27 +02:00
Philipp Kunz	cb0ab2c9db	fix(core): update	2024-05-27 17:34:26 +02:00
Philipp Kunz	2a17ee542e	3.0.8	2024-05-27 14:34:13 +02:00
Philipp Kunz	95e9d2f0ff	fix(core): update	2024-05-27 14:34:12 +02:00
Philipp Kunz	1a71c76da3	3.0.7	2024-05-27 12:56:26 +02:00
Philipp Kunz	e924511147	fix(s3 paths): pathing differences now correctly handled in a reducePath method.	2024-05-27 12:56:25 +02:00
Philipp Kunz	645ebbdd4d	3.0.6	2024-05-21 18:47:00 +02:00
Philipp Kunz	168148b2c9	fix(core): update	2024-05-21 18:46:59 +02:00