⚡ socketscript

A scalable, TypeScript-first real-time socket server framework for modular, API-driven applications.

socketscript enables developers to create powerful WebSocket-based microservices with namespaced event routing, schema validation using Zod, secure middleware, and deep integration with REST APIs.

🚀 Features

• ✅ Modular Subscription architecture
• ✅ Namespace + Room support (e.g. /admin, finance-team)
• ✅ Built-in middleware for token-based auth
• ✅ CLI tool to scaffold subscriptions quickly
• ✅ Zod schema validation for incoming payloads
• ✅ Works as a microservice that connects to any API
• ✅ Redis adapter support for scalable deployments
• ✅ Full TypeScript support with generics

📦 Installation

npm install socketscript

If using the CLI:

npm install -g socketscript-cli

🧠 Core Concepts

1. Create a Subscription

// src/subscriptions/transactions.ts
import { z } from 'zod';
import { Subscription } from 'socketscript';

export const transactionsSubscription: Subscription = {
  name: 'transactions',
  namespace: '/transactions',
  room: 'finance',
  listenOn: ['newTx'],
  emitOn: ['txStatus'],
  schema: z.object({
    userId: z.string(),
    amount: z.number().positive(),
  }),
  handler: async (data, socket, context) => {
    // Forward to your API
    return {
      ...data,
      status: 'received',
      receivedAt: new Date().toISOString(),
    };
  },
};

2. Register Subscription in Your Socket Server

// src/index.ts
import { Socketscript } from 'socketscript';
import { transactionsSubscription } from './subscriptions/transactions';

const server = new Socketscript({ port: 4000 });

server.register(transactionsSubscription);

3. Scaffold Subscriptions with CLI

socketscript generate-subscription transactions \
  --namespace /transactions \
  --room finance \
  --events newTx:txStatus \
  --validate

⚙️ API

register(subscription)

Registers a subscription object. Supports:

• namespace
• room
• listenOn, emitOn
• middleware
• schema (Zod)

useRedisAdapter(pubClient, subClient)

Adds Redis adapter for scaling with multiple instances.

🔒 Example Auth Middleware

middleware: async (socket, next) => {
  const token = socket.handshake.auth?.token;
  const isValid = await verifyToken(token);
  isValid ? next() : next(new Error('Unauthorized'));
}

🧪 Testing

Built-in support for:

• Type-safe handlers
• Mockable Zod schemas
• Unit and integration test-ready structure

🧰 Tools

| Tool | Description | |------------------|-----------------------------------| | socketscript | Core real-time socket engine | | socketscript-cli | CLI scaffolding for subscriptions |