@torquedev/ext-storage

File storage service for Torque with bundle-scoped namespaces, SQLite metadata tracking, and a local filesystem adapter. Each bundle gets an isolated storage namespace to prevent cross-bundle file access.

Install

npm install github:michaeljabbour/torque-ext-storage

Peer dependencies: @torquedev/core >=0.1.0, better-sqlite3 >=11.0.0

Usage

import { StorageService } from '@torquedev/ext-storage';

const storageService = new StorageService({ db, config: {
  adapter: 'local',
  path: './data/storage',
}});

coordinator.registerService('storage', storageService);

Bundles receive scoped storage that auto-namespaces all keys:

const storage = storageService.scopedTo('documents');

storage.store('contracts/abc.pdf', buffer, { mime: 'application/pdf' });
storage.getUrl('contracts/abc.pdf');
// '/storage/documents/contracts/abc.pdf'

API

StorageService

store(key, content, metadata?)

Store a file and record its metadata. Re-storing an existing key updates the record (upsert).

• key -- storage path (e.g. 'documents/contracts/abc.pdf')
• content -- Buffer or string
• metadata -- { mime, original_name, uploaded_by, bundle, metadata }

Returns: { id, key, size, mime, created_at }

retrieve(key)

Returns a ReadableStream for the file, or null if not found.

retrieveBuffer(key)

Returns the file content as a Buffer, or null.

getUrl(key, options?)

Returns a URL for direct client download. Local adapter returns /storage/{key}.

remove(key)

Deletes the file and its metadata row. Returns { success: boolean }.

list(prefix?, options?)

List files matching a key prefix, with metadata. Options: limit (default: 100), offset, bundle.

getMetadata(key)

Returns the full metadata row for a file, or null.

scopedTo(bundleName)

Returns a BundleScopedStorage instance that prefixes all keys with bundleName/.

BundleScopedStorage

Wraps StorageService with automatic key prefixing. Exposes the same methods: store, retrieve, retrieveBuffer, getUrl, remove, list, getMetadata.

Security

All storage keys are sanitized before use:

• .. sequences are stripped (directory traversal prevention)
• Null bytes are removed
• Leading slashes are stripped
• Multiple consecutive slashes are collapsed

Exports

import { StorageService, BundleScopedStorage } from '@torquedev/ext-storage';

Testing

npm test

ESM-only. Requires Node.js with the built-in test runner.

License

MIT