Skip to main content

Quik Framework :: Storage

Handles file storage with local and S3 implementations. The module initializes storage engines when an HTTP engine is available.

Installation​

npm install @quik/storage

Configuration​

Local:

  • STORAGE_LOCAL_ENABLED
  • STORAGE_LOCAL_UPLOAD (default: ./temp)
  • STORAGE_LOCAL_DESTINATION (default: ./storage)
  • STORAGE_LOCAL_PUBLIC_URL (default: empty, returns relative paths)
  • STORAGE_LOCAL_SIGNED_SECRET (default: empty; required to generate signed local storage URLs)
  • STORAGE_LOCAL_SIGNED_UPLOAD_EXPIRE (default: 60 seconds)
  • STORAGE_LOCAL_SIGNED_DOWNLOAD_EXPIRE (default: 60 seconds)
  • STORAGE_LOCAL_HTTP_BASE_PATH (default: /storage/local)

S3:

  • STORAGE_S3_ENABLED
  • STORAGE_S3_REGION
  • STORAGE_S3_ENDPOINT
  • STORAGE_S3_PATH_STYLE
  • STORAGE_S3_ACCESS_KEY
  • STORAGE_S3_SECRET_KEY
  • STORAGE_S3_BUCKET
  • STORAGE_S3_SIGNED_UPLOAD_EXPIRE
  • STORAGE_S3_SIGNED_DOWNLOAD_EXPIRE

Usage​

Local storage engine:

import { QLocalStorageEngine, StorageStore } from '@quik/storage';

const engine = new QLocalStorageEngine();
StorageStore.register(engine.name, engine);
const file = await engine.get('uploads/avatar.png');
const url = await file.getUrl();

Signed S3 URLs:

import { PresignedS3URLEntity, QS3StorageEngine, StorageStore } from '@quik/storage';

const engine = new QS3StorageEngine();
StorageStore.register(engine.name, engine);
const url = await PresignedS3URLEntity.getUploadURL('uploads/avatar.png');

Signed local storage URLs (requires STORAGE_LOCAL_SIGNED_SECRET to be set):

import { PresignedLocalURLEntity, QLocalStorageEngine, StorageStore } from '@quik/storage';

const engine = new QLocalStorageEngine();
StorageStore.register(engine.name, engine);
const url = await PresignedLocalURLEntity.getDownloadURL('uploads/avatar.png');

The returned URL is built from STORAGE_LOCAL_HTTP_BASE_PATH ({basePath}/download?token=... or /upload?token=...) — this package only signs and verifies the token via LocalSignature.sign/verify; it does not register any HTTP routes. The consuming application (or @quik/storage-express's RequireLocalStorageToken decorator) is responsible for mounting a route at a matching path that verifies the token before streaming or writing the file. Note getUrl() on QLocalStorageEngine is unaffected by signing — it keeps returning a static path (optionally prefixed with STORAGE_LOCAL_PUBLIC_URL).

Create and refresh file metadata:

import { QLocalStorageEngine, QStorageFile, StorageStore } from '@quik/storage';

const engine = new QLocalStorageEngine();
StorageStore.register(engine.name, engine);

const file = new QStorageFile();
file.fill({
  fileName: 'hello.txt',
  encoding: 'utf-8',
  mimeType: 'text/plain',
  path: '',
  size: 5,
  extension: '.txt',
  engine: engine.name,
  contents: Buffer.from('hello').toString('base64')
});

const created = await engine.create(file, 'uploads/hello.txt');
const refreshed = await created.reload();

Create directly from contents:

const base64 = Buffer.from('hello world').toString('base64');
const stored = await engine.new('uploads/hello.txt', base64, { fill: true });
console.log(stored.size); // 11

Streaming​

Use streaming helpers when dealing with large files:

import { createReadStream } from 'node:fs';

await engine.saveStream('uploads/big.bin', createReadStream('/tmp/big.bin'));
const stream = await engine.readStream('uploads/big.bin');

Notes:

  • QStorageFile.reload() returns the same instance when it is not sealed, and a new instance when it is sealed.
  • If the underlying file cannot be found, reload() returns the current instance unchanged.

Engine Notes​

  • Local storage paths are resolved relative to STORAGE_LOCAL_DESTINATION unless you supply absolute paths.
  • S3 paths are object keys. Avoid leading slashes to keep keys consistent.
  • read() and save() load entire contents into memory; prefer readStream() and saveStream() for large files.

API Highlights​

  • QLocalStorageEngine and QStorageFile entity.
  • QS3StorageEngine and PresignedS3URLEntity.
  • PresignedLocalURLEntity for signed local storage URLs.
  • Engine helpers: new / create, move, copy, remove, removeFolder, importFromPath, getUrl, getSignedDownloadURL, and getSignedUploadURL.
  • Store helpers: StorageStore.getDefault().
  • File helpers: QStorageFile.reload() and getMimeType().

Testing & Coverage​

See the root instructions for details on running pnpm run test:coverage and accessing coverage artifacts.

API Reference​

Generated API documentation is available in the storage API section.