StreamBy Core Middleware

0.26.10 verified Thu Apr 23 auth: no javascript

@streamby/core is a robust, plug-and-play middleware framework designed for integrating storage-agnostic media management capabilities into existing Express.js (or compatible) applications. Currently at version `0.26.10`, the package provides functionality for file uploads, listings, and multi-project access across various storage providers like AWS S3, with planned support for Google Cloud Storage, Cloudflare R2, and local servers. It aims for a rapid, minor version release cadence, indicating active development and feature enhancements. A key differentiator is its architectural approach: it operates as a library within your existing API, eliminating the need to deploy and manage a separate backend service for media handling. This design promotes tight integration and simplifies deployment, offering a flexible solution for developers building scalable media-centric applications who require fine-grained control over their backend stack and data.

Common errors

error WebSocket connection failed ↓

cause The WebSocket server is not correctly bound to or sharing the HTTP server instance.

fix

Ensure http.createServer(app) is used to create the server, and this server object is passed to both server.listen() and the WebSocketServer({ server }) constructor.

error Error: relation 'streamby.files' does not exist ↓

cause The necessary database schema for StreamBy Core has not been initialized or is inaccessible.

fix

Run the appropriate database schema setup function (setupStreambyPg for PostgreSQL or setupStreambyMongo for MongoDB) at your application's initialization phase, providing a connected database client/pool.

Warnings

gotcha When integrating `@streamby/core` with WebSocket functionality, it is crucial to use `http.createServer(app)` instead of `app.listen()` for the Express application. This ensures the `WebSocketServer` can share the same underlying HTTP server and port, preventing conflicts or connection failures. ↓

fix Wrap your Express `app` instance with `http.createServer(app)` and pass the resulting `server` object to both `server.listen()` and the `WebSocketServer({ server })` constructor.

gotcha StreamBy Core requires a pre-configured database schema (tables/collections and indexes) for its internal operations. It does not manage database connections or schema creation directly. Failing to initialize the schema will result in runtime errors when StreamBy Core attempts to access its data. ↓

fix At application startup, before any StreamBy operations, explicitly call the appropriate setup function: `setupStreambyPg({ pool, schema: 'streamby' })` for PostgreSQL or `setupStreambyMongo({ client, dbName: 'streamby' })` for MongoDB.

Install

npm install streamby-core

yarn add streamby-core

pnpm add streamby-core

Imports

createStreamByRouter
wrong
```
const { createStreamByRouter } = require('@streamby/core');
```
correct
```
import { createStreamByRouter } from '@streamby/core';
```
The package is primarily designed for ESM/TypeScript environments. While CommonJS `require` might work with transpilation, direct ESM imports are preferred.
setupStreambyPg
wrong
```
import { setupStreambyPg } from '@streamby/core';
```
correct
```
import { setupStreambyPg } from '@streamby/core/pg/setup';
```
This is a subpath import for PostgreSQL-specific database schema setup. Ensure the full path is used.
setupStreambyMongo
wrong
```
import { setupStreambyMongo } from '@streamby/core';
```
correct
```
import { setupStreambyMongo } from '@streamby/core/mongo/setup';
```
This is a subpath import for MongoDB-specific database schema setup. Ensure the full path is used.

Quickstart

Demonstrates setting up an Express server with StreamBy core middleware, integrating an S3 storage provider, dummy authentication, and a WebSocket server for real-time capabilities. Requires `ws` and `@types/ws`.

import http from 'http';
import express from 'express';
import { WebSocketServer } from 'ws';
import { createStreamByRouter } from '@streamby/core';

const app = express();
const server = http.createServer(app);
const wss = new WebSocketServer({ server, path: '/streamby/ws' });

app.use('/streamby', express.json(), createStreamByRouter({
  authProvider: async (req) => {
    // In a real application, validate token/session and return user info
    return { userId: 'user-id-123', username: 'demo-user', role: 'admin' };
  },
  databases: [
    { id: 'mongo', type: 'nosql', connectionString: process.env.MONGO_URI ?? 'mongodb://localhost:27017/streamby_test' },
    { id: 'postgres', type: 'sql', connectionString: process.env.POSTGRES_URI ?? 'postgresql://user:password@localhost:5432/streamby_test', main: true }
  ],
  storageProviders: [
    {
      type: 's3',
      config: {
        bucket: process.env.AWS_BUCKET ?? 'your-s3-bucket-name',
        region: process.env.AWS_REGION ?? 'us-east-1',
        accessKeyId: process.env.AWS_ACCESS_KEY ?? 'YOUR_AWS_ACCESS_KEY_ID',
        secretAccessKey: process.env.AWS_SECRET_KEY ?? 'YOUR_AWS_SECRET_ACCESS_KEY'
      }
    }
  ],
  encrypt: process.env.STREAMBY_ENCRYPTION_KEY ?? 'a_32_character_encryption_key_for_streamby',
  websocket: { server: wss }
}));

server.listen(3000, () => {
  console.log('StreamBy Core example server listening on port 3000');
});