Migration Guide

This document covers version-to-version migration instructions for StreetJS Framework.

Package rename: @streetjs/core → streetjs

The framework’s primary package was renamed from @streetjs/core to streetjs. The old package is now a deprecated backward-compatibility shim that re-exports streetjs unchanged — the export surface is identical.

New projects:

1
2

- npm install @streetjs/core
+ npm install streetjs

1
2

- import { streetApp, Controller, Get } from '@streetjs/core';
+ import { streetApp, Controller, Get } from 'streetjs';

Subpath imports map 1:1 as well (@streetjs/core/http → streetjs/http, /router, /database, /security, …).

Existing projects require no immediate change: @streetjs/core continues to work because it re-exports streetjs. To migrate, update your dependency and rewrite the import specifier as above. There are no API changes — every named export and subpath is preserved (verified by the export-parity test suite).

@streetjs/core is deprecated and will only receive the re-export shim going forward. Please migrate to streetjs.

v1.x → v2.0

Breaking Changes

Router API

The Router class no longer accepts a prefix option in the constructor. Use @Controller prefix instead.

1
2
3
4
5
6

// Before (v1.x)
const router = new Router({ prefix: '/api' });

// After (v2.0)
@Controller('/api')
class ApiController { ... }

Pool Configuration

PgPool now requires explicit minConnections and maxConnections:

1
2
3
4
5
6
7
8
9

// Before (v1.x)
new PgPool({ host, port, user, password, database });

// After (v2.0)
new PgPool({
  host, port, user, password, database,
  minConnections: 2,
  maxConnections: 10,
});

New in v2.0

  • Multi-tenancy with TenantPoolRegistry
  • RBAC with RbacService
  • OAuth2/OIDC with OAuthManager
  • WebAuthn/Passkeys with WebAuthnService
  • Job queue with JobQueue and CronScheduler
  • Workflow engine with WorkflowEngine

Database Migrations

Run the following after upgrading:

1

street migrate:run

New migration tables added: street_sessions, street_audit_log, street_refresh_tokens, street_api_keys, street_webauthn_credentials.

v2.0 → v2.1

Changes

Multi-region replication

The ReplicationCoordinator now requires explicit RegionConfig[]:

1
2
3
4

const coordinator = new ReplicationCoordinator([
  { name: 'us-east', pool: primaryPool, primary: true },
  { name: 'eu-west', pool: replicaPool, readWeight: 1 },
]);

Feature Flags

Feature flag rules are now evaluated with OR semantics (any matching rule enables the flag).

1
2

# Apply feature flags migration
street migrate:run

v2.1 → v2.2 (Enterprise)

New Features

  • AuditLogger with HMAC hash-chain signing
  • @RetainFor, @Encrypt, @Classify property decorators
  • RetentionJob for automated data purging
  • ComplianceReporter for regulatory reporting
  • BackupService with LocalStorageAdapter

Database Migrations

Add these SQL blocks to your migration files:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

-- Feature flags
CREATE TABLE IF NOT EXISTS street_feature_flags (
  name TEXT PRIMARY KEY,
  enabled BOOLEAN DEFAULT false,
  rules JSONB DEFAULT '[]',
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Enterprise audit log
CREATE TABLE IF NOT EXISTS street_audit_log (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  category TEXT NOT NULL,
  actor_id TEXT,
  action TEXT NOT NULL,
  resource TEXT,
  before_state JSONB,
  after_state JSONB,
  ip TEXT,
  user_agent TEXT,
  batch_id UUID,
  signature TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Backups registry
CREATE TABLE IF NOT EXISTS street_backups (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  size_bytes BIGINT,
  duration_ms INT,
  checksum TEXT,
  storage_key TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

v2.2 → v3.0 (Platform)

New Features

  • DistributedCache with InProcessCacheTransport
  • GlobalConfigService with pub/sub config propagation
  • EventStreamConsumer and RealtimeAggregator
  • ReplicationCoordinator with automatic failover
  • AI Toolkit: OpenAiClient, AnthropicClient, OllamaClient, AgentExecutor
  • Plugin Marketplace: PluginModule, PluginInstaller
  • Edge Runtime: handleEdgeRequest adapter

Breaking Changes

InProcessTransport renamed

The InProcessTransport in @streetjs/core/microservices is unchanged. The new InProcessStreamTransport is in event-streaming.ts — these are separate classes.

Upgrade Steps

  1. Update @streetjs/core to ^3.0.0
  2. Update @streetjs/cli to ^3.0.0
  3. Run street migrate:run
  4. Update any custom middleware that accesses ctx.state['readPool'] — this is now set by preferredRegionMiddleware