blendsdk

blendsdk

Enterprise-grade TypeScript SDK for web applications, database operations, caching, pub/sub, email, i18n, and code generation.

Installation

npm install blendsdk

Available Modules

Module	Import	Description	Peer Deps Required
stdlib	blendsdk/stdlib	Type guards, utilities, helpers	—
cmdline	blendsdk/cmdline	CLI argument parser	—
expression	blendsdk/expression	Immutable SQL WHERE clause builder	—
dbcore	blendsdk/dbcore	Database abstractions, CRUD statement builders	—
postgresql	blendsdk/postgresql	PostgreSQL client + connection pooling	pg, yesql
webafx	blendsdk/webafx	Express 5 web framework with DI, plugins, routing	express, cors, helmet, cookie-parser
webafx-cache	blendsdk/webafx-cache	Caching + pub/sub (Redis and in-memory backends)	ioredis
webafx-mailer	blendsdk/webafx-mailer	Email sending (SMTP and in-memory backends)	nodemailer
webafx-auth	blendsdk/webafx-auth	Token validation plugin (JWT/OIDC)	jose
i18n	blendsdk/i18n	Internationalization core (Translator, catalogs)	—
i18n-node	blendsdk/i18n-node	i18n Node.js sources (JSON files, content files)	—
webafx-i18n	blendsdk/webafx-i18n	i18n webafx plugin (locale resolution)	—
codegen	blendsdk/codegen	Code generators (TypeScript, Zod, OpenAPI, SQL)	pg, postgres-array

Quick Start

Web API with Express 5

import { WebApplication, BaseController, RouteDefinition } from "blendsdk/webafx";

// Define a controller with routes
class HelloController extends BaseController {
  routes(): RouteDefinition[] {
    return [
      this.route()
        .get("/hello")
        .handle(async (_req, res) => {
          this.ok(res, { message: "Hello from BlendSDK!" });
        }),
    ];
  }
}

// Create the application and register the controller
const app = new WebApplication({
  PORT: 3000,
  ENV_MODE: "development",
});

app.registerController("/api", HelloController);

const shutdown = await app.start();
// Server running → GET /api/hello returns { success: true, data: { message: "Hello from BlendSDK!" } }

SQL Expression Building

import { query } from "blendsdk/expression";

// Build a type-safe WHERE clause
const filter = query()
  .where("status").equals("active")
  .and("age").greaterThanOrEqual(18);

// Compile to parameterized SQL
const { sql, params } = filter.compile();
// sql: "status = :p1 AND age >= :p2"
// params: { p1: "active", p2: 18 }

// Nested conditions with grouping
const advanced = query()
  .where("status").equals("active")
  .and(q => q
    .where("age").greaterThan(21)
    .or("verified").equals(true)
  )
  .compile();
// sql: "status = :p1 AND (age > :p2 OR verified = :p3)"
// params: { p1: "active", p2: 21, p3: true }

CLI Argument Parser

import { CommandLineParser } from "blendsdk/cmdline";

const cli = new CommandLineParser({ name: "my-cli", version: "1.0.0" });

cli.addCommand({
  name: "deploy",
  description: "Deploy the application",
  options: [
    {
      name: "environment",
      short: "e",
      type: "string",
      required: true,
      choices: ["dev", "staging", "production"],
    },
    {
      name: "verbose",
      short: "v",
      type: "boolean",
      description: "Verbose output",
    },
  ],
  handler: async (params) => {
    console.log(`Deploying to ${params.environment}...`);
  },
});

await cli.execute();
// Usage: my-cli deploy --environment=staging --verbose

Database CRUD Operations

import { Database } from "blendsdk/dbcore";

// Insert with returning clause
const user = await db
  .insert<{ name: string; email: string }>("users")
  .values({ name: "Alice", email: "[e-mail]" })
  .returning("*")
  .execute();

// Update with filter
await db
  .update<{ name: string }, { id: number }>("users")
  .values({ name: "Bob" })
  .filter({ id: 1 })
  .returning("*")
  .execute();

// Delete with expression filter
await db
  .delete<{ status: string }>("users")
  .filterByExpression(q => q.where("status").equals("inactive"))
  .execute();

Caching

import { MemoryCacheProvider } from "blendsdk/webafx-cache";

const cache = new MemoryCacheProvider({
  rootKey: "MyApp",
  defaultTTL: 300, // 5 minutes
});

// Simple set/get with type safety
await cache.set("user:1", { name: "Alice", role: "admin" });
const user = await cache.get<{ name: string; role: string }>("user:1");

// Cache-aside pattern (getOrSet)
const product = await cache.getOrSet(
  "product:42",
  async () => {
    return await fetchProductFromDatabase(42);
  },
  60, // TTL in seconds
);

// Pattern-based deletion
await cache.deletePattern("user:*"); // Remove all user cache entries

Pub/Sub Messaging

import { MemoryPubSubProvider } from "blendsdk/webafx-cache";

const pubsub = new MemoryPubSubProvider();

// Subscribe to a specific channel with typed messages
await pubsub.subscribe<{ id: number; total: number }>("order:new", (msg) => {
  console.log(`New order on ${msg.channel}:`, msg.data);
});

// Pattern subscription (wildcard matching)
await pubsub.psubscribe("order:*", (msg) => {
  console.log(`Order event [${msg.pattern}] on ${msg.channel}`);
});

// Publish returns the number of receivers
const receiverCount = await pubsub.publish("order:new", { id: 1, total: 99.99 });

Internationalization

import { Translator } from "blendsdk/i18n";

const translator = new Translator({
  defaultLocale: "en",
  catalog: {
    greeting: { en: "Hello ${name}", nl: "Hallo ${name}" },
    farewell: { en: "Goodbye", nl: "Tot ziens" },
    book: {
      en: ["${count} book", "${count} books"],
      nl: ["${count} boek", "${count} boeken"],
    },
  },
});

translator.translate("greeting", "en", { name: "Alice" }); // "Hello Alice"
translator.translate("greeting", "nl", { name: "Alice" }); // "Hallo Alice"
translator.translate("book", "en", { count: 1 });           // "1 book"
translator.translate("book", "en", { count: 5 });           // "5 books"
translator.translate("farewell", "en_GB");                   // "Goodbye" (falls back to "en")

Utilities

import { isNullOrUndef, isString } from "blendsdk/stdlib";

const value: unknown = getUserInput();

if (!isNullOrUndef(value) && isString(value)) {
  console.log("Got a string:", value);
}

Peer Dependencies

Install only the peer dependencies for the modules you use:

# Web framework (webafx)
npm install express cors helmet cookie-parser

# PostgreSQL database (postgresql, codegen)
npm install pg yesql

# Redis caching + pub/sub (webafx-cache)
npm install ioredis

# Email sending (webafx-mailer)
npm install nodemailer

# Authentication — JWT/OIDC (webafx-auth)
npm install jose

# Code generation (codegen)
npm install pg postgres-array

Requirements

• Node.js >= 22.0.0
• TypeScript >= 5.6.0 (peer dependency)
• ESM only — this package uses "type": "module"

Links

• GitHub Repository
• Contributing Guide
• License (MIT)

Author

TrueSoftware B.V.