@semantq/storage

@semantq/storage

File storage module for semantqQL — the Node.js backend of the semantq framework.

Organizes files by model record structure (e.g., product/1/images/) and provides a unified API across multiple storage providers.

Installation

npm install @semantq/storage

Quick Start

import { Storage } from '@semantq/storage';

// Upload a file (from multer, Buffer, or File object)
const result = await Storage.upload(fileBuffer, {
  organizationId: 1,
  modelName: 'ProjectFile',
  recordId: 'abc-123',
  fieldKey: 'fileUrl',
  originalName: 'document.pdf',
  mimeType: 'application/pdf'
});

// result: { storageKey, publicUrl, fileSize, fileHash, metadata }

// Get a public URL
const url = await Storage.getUrl(result.storageKey);

// Check if file exists
const exists = await Storage.exists(result.storageKey);

// Get file as buffer
const buffer = await Storage.getBuffer(result.storageKey);

// Delete file
await Storage.delete(result.storageKey);

API

Storage.upload(file, metadata)

Upload a file. Accepts a Buffer, multer file object, or browser File instance.

Option	Type	Required	Description
organizationId	string/number	Yes	Organization ID
modelName	string	Yes	Model name (e.g., ProjectFile, Budget)
recordId	string	Yes	Record UUID
fieldKey	string	Yes	Field name (e.g., fileUrl)
originalName	string	No	Original filename
mimeType	string	No	File MIME type

Returns: { storageKey, publicUrl, fileSize, fileHash, metadata }

Storage.delete(storageKey)

Delete a file from storage. Returns boolean.

Storage.getUrl(storageKey)

Get the public URL for a file. Returns string.

Storage.getBuffer(storageKey)

Download file as a Buffer. Returns Buffer.

Storage.exists(storageKey)

Check if file exists in storage. Returns boolean.

Storage Key Structure

Files are stored with a structured path pattern:

{organizationId}/{modelName}/{recordId}/{fieldKey}/{filename}

Example:

1/projectfile/abc-123/fileurl/document_1711234567890_a1b2c3.pdf

Providers

Local (Default)

Stores files on the local filesystem. Configure in server.config.js:

storage: {
  activeProvider: 'local',
  local: {
    uploadDir: './uploads',
    baseUrl: '/uploads'
  }
}

UploadThing (Planned)

Cloud storage via UploadThing. Falls back to local provider when no token is configured.

S3 (Coming Soon)

AWS S3 provider.

Cloudinary (Coming Soon)

Cloudinary provider.

Configuration

All storage configuration lives in your SemantQQL server.config.js under the storage key:

export default {
  storage: {
    activeProvider: 'local',    // 'local' | 'uploadthing' | 's3' | 'cloudinary'
    local: {
      uploadDir: './uploads',
      baseUrl: '/uploads'
    },
    uploadthing: {
      token: process.env.UPLOADTHING_TOKEN,
      appId: process.env.UPLOADTHING_APP_ID
    }
    // s3: { ... }        (coming soon)
    // cloudinary: { ... } (coming soon)
  }
}

Usage in Services

import { Storage } from '@semantq/storage';

class ProjectFileService {
  async uploadFile(req) {
    const file = req.file;
    const userData = req.userData;

    const result = await Storage.upload(file, {
      organizationId: userData.organizationId,
      modelName: 'ProjectFile',
      recordId: req.body.projectId,
      fieldKey: 'fileUrl',
      originalName: file.originalname,
      mimeType: file.mimetype
    });

    // Save result.storageKey and result.publicUrl to your database
    await ProjectFileModel.create({
      filename: file.originalname,
      fileUrl: result.publicUrl,
      fileKey: result.storageKey,
      // ... other fields
    });
  }

  async deleteFile(fileId) {
    const file = await ProjectFileModel.findById(fileId);
    if (file?.fileKey) {
      await Storage.delete(file.fileKey);
    }
    await ProjectFileModel.delete(fileId);
  }
}

Extending

To add a new provider, extend BaseStorageProvider:

import { BaseStorageProvider } from '@semantq/storage';

class MyProvider extends BaseStorageProvider {
  constructor(config) {
    super(config);
    this.name = 'myprovider';
  }

  async upload(fileBuffer, options) { /* ... */ }
  async delete(storageKey) { /* ... */ }
  async getUrl(storageKey) { /* ... */ }
  async exists(storageKey) { /* ... */ }
  async getBuffer(storageKey) { /* ... */ }
}

License

MIT