@push.rocks/smartbucket/readme.hints.md

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.

* 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!
* **BucketWatcher** - Polling-based S3 change watcher (`bucket.createWatcher()`). Detects add/modify/delete via ETag/Size/LastModified comparison. Supports RxJS Observable pattern (`changeSubject`) and EventEmitter pattern (`on('change')`). Options: `prefix`, `pollIntervalMs`, `bufferTimeMs`, `includeInitial`, `pageSize`.
* **@git.zone/tsbuild 4.4.x**: tsconfig explicitly declares `"types": ["node"]` so Node globals/modules are available when tsbuild passes files programmatically to TypeScript.
* **Test assertions**: Use `@git.zone/tstest/tapbundle` for `tap` and `expect`. Note that smartexpect's `toEqual` does NOT support `expect.any()` matchers (only `toMatchObject` does, and only at the top level). For testing nested objects with type matchers, use `toHaveProperty` + `toBeTypeofNumber/String/Boolean` separately.