tempest-express-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mauricio Benjamin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# tempest-express-sdk
+
+> Shared **Express + Zod + tempest-db-js** building blocks — a Node.js/TypeScript
+> port of the conventions in [`tempest-fastapi-sdk`](https://pypi.org/project/tempest-fastapi-sdk/).
+
+📖 **Documentation:** [Português (BR)](https://mauriciobenjamin700.github.io/tempest-express-sdk/) · [English (US)](https://mauriciobenjamin700.github.io/tempest-express-sdk/en/)
+
+Strict TypeScript, `@`-alias imports (no `.js` suffixes), native **Swagger UI +
+Redoc** generated straight from your Zod schemas, and a layered
+router → controller → service → repository → model stack built on
+[`tempest-db-js`](https://www.npmjs.com/package/tempest-db-js).
+
+> ⚠️ **Status: pre-alpha (v0.1.0).** Foundation layer is built and tested; many
+> `tempest-fastapi-sdk` feature modules are not yet ported (see Roadmap).
+
+## Install
+
+```bash
+npm install tempest-express-sdk tempest-db-js express zod
+```
+
+`tempest-db-js` is a required peer dependency.
+
+## What's inside
+
+| Area | Exports |
+| --- | --- |
+| **core** | `JSONLogger`, `configureLogging`, request-id context (`getRequestId`, `runWithRequestContext`), `defineEnum` |
+| **exceptions** | `AppException` + `ConflictException` / `NotFoundException` / `UnauthorizedException` / `ForbiddenException` / `ValidationException` / `TooManyRequestsException` / `InvalidTokenException` / `ExpiredTokenException`, `MessageCatalog` (i18n) |
+| **schemas** | `z` (OpenAPI-augmented), `baseResponseSchema`, `toDict`, `paginationFilterSchema` / `paginationSchema`, cursor pagination, `encodeCursor` / `decodeCursor` |
+| **settings** | `loadSettings`, `baseAppSettingsShape` (server / database / CORS) |
+| **db** | re-exports `tempest-db-js` + `BaseModel`, `tableNameFor`, soft-delete / audit column helpers |
+| **services / controllers** | `BaseService`, `BaseController` over a typed repository |
+| **api** | `createApp`, `runServer`, `registerExceptionHandlers`, `createOpenApiRegistry`, `generateOpenApiDocument`, `mountSwaggerUi`, `mountRedoc`, `makeHealthRouter` |
+
+## Quick start
+
+```ts
+import { createApp, createOpenApiRegistry, runServer, z } from "tempest-express-sdk";
+
+const registry = createOpenApiRegistry();
+const Item = registry.register("Item", z.object({ id: z.string().uuid(), name: z.string() }));
+
+const app = await createApp({
+  corsOrigins: "*",
+  openapi: { registry, info: { title: "My API", version: "1.0.0" } },
+  configure: (app) => {
+    app.get("/api/items", (_req, res) => res.json([]));
+  },
+});
+
+await runServer(app, { host: "127.0.0.1", port: 8000 });
+// Swagger UI → /docs   ·   Redoc → /redoc   ·   spec → /openapi.json   ·   health → /health
+```
+
+## CLI
+
+```bash
+npx tempest-express new my-service   # scaffold a runnable layered service
+cd my-service && npm install && npm run dev
+```
+
+The generated project is a complete vertical slice (model → repository → service
+→ controller → router → app) pre-wired with `createApp`, Swagger/Redoc and Zod.
+
+## Develop
+
+```bash
+npm install
+npm run test:types   # tsc --noEmit
+npm test             # vitest
+npm run build        # tsup → dual ESM + CJS + .d.ts (+ CLI bin)
+npm run lint         # biome
+```
+
+## Roadmap
+
+Ported: core, exceptions (+ i18n), schemas, pagination, settings, `BaseModel`,
+`BaseRepository`/`BaseService`/`BaseController`, `createApp` + Swagger/Redoc,
+health, CLI `new`.
+
+Also ported: BR utils (CPF/CNPJ/CEP/phone/UF + cities), `PasswordUtils`,
+`JWTUtils`, opaque tokens, `AttemptThrottle`, the `auth` module (signup/login/
+refresh + JWT guards), CLI `generate`/`secret`/`docker-compose`, and the
+bilingual MkDocs docs site.
+
+Not yet ported from `tempest-fastapi-sdk`: sessions, cache (Redis), queue
+(RabbitMQ), tasks, webpush, websockets, feature flags, object storage, metrics,
+admin, SSE, and the MFA / email / password-reset flows.
+
+## License
+
+MIT

package/dist/chunk-2NB7ZA7G.js

@@ -0,0 +1,6 @@
+// src/version.ts
+var VERSION = "0.1.0";
+
+export { VERSION };
+//# sourceMappingURL=chunk-2NB7ZA7G.js.map
+//# sourceMappingURL=chunk-2NB7ZA7G.js.map

package/dist/chunk-2NB7ZA7G.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/version.ts"],"names":[],"mappings":";AACO,IAAM,OAAA,GAAU","file":"chunk-2NB7ZA7G.js","sourcesContent":["/** The installed SDK version. Single source of truth for the barrel + CLI. */\nexport const VERSION = \"0.1.0\";\n"]}

package/dist/cli.cjs

@@ -0,0 +1,546 @@
+#!/usr/bin/env node
+'use strict';
+
+var crypto = require('crypto');
+var promises = require('fs/promises');
+var path = require('path');
+var util = require('util');
+
+// src/cli/template.ts
+var SDK_VERSION = "^0.1.0";
+function projectFiles(name) {
+  return {
+    "package.json": `${JSON.stringify(
+      {
+        name,
+        version: "0.1.0",
+        private: true,
+        type: "module",
+        scripts: {
+          dev: "tsx watch main.ts",
+          start: "tsx main.ts",
+          build: "tsc -p tsconfig.json",
+          typecheck: "tsc --noEmit"
+        },
+        dependencies: {
+          express: "^5.1.0",
+          "tempest-db-js": "^0.1.0",
+          "tempest-express-sdk": SDK_VERSION,
+          zod: "^3.24.1"
+        },
+        devDependencies: {
+          "@types/express": "^5.0.0",
+          "@types/node": "^22.10.0",
+          tsx: "^4.19.2",
+          typescript: "^5.7.0"
+        }
+      },
+      null,
+      2
+    )}
+`,
+    "tsconfig.json": `${JSON.stringify(
+      {
+        compilerOptions: {
+          target: "ES2022",
+          module: "ESNext",
+          moduleResolution: "Bundler",
+          lib: ["ES2022"],
+          strict: true,
+          noUncheckedIndexedAccess: true,
+          verbatimModuleSyntax: true,
+          esModuleInterop: true,
+          skipLibCheck: true,
+          forceConsistentCasingInFileNames: true,
+          outDir: "dist",
+          paths: { "@/*": ["./src/*"] }
+        },
+        include: ["src", "main.ts"]
+      },
+      null,
+      2
+    )}
+`,
+    ".gitignore": "node_modules\ndist\n.env\n*.log\n",
+    ".env.example": "HOST=127.0.0.1\nPORT=8000\nDEBUG=false\nDATABASE_URL=sqlite://./app.db\nCORS_ORIGINS=*\n",
+    "main.ts": `import { run } from "@/index";
+
+run();
+`,
+    "src/index.ts": `import { run } from "@/server";
+
+export { run };
+`,
+    "src/core/settings.ts": `import { baseAppSettingsShape, loadSettings, z } from "tempest-express-sdk";
+
+/** Application settings \u2014 extend the SDK base shape with project fields. */
+export const settingsSchema = z.object({
+  ...baseAppSettingsShape,
+});
+
+export const settings = loadSettings(settingsSchema);
+`,
+    "src/db/models/itemModel.ts": `import { BaseModel, column, tableNameFor } from "tempest-express-sdk";
+
+/** A sample domain model. Replace with your own. */
+export class ItemModel extends BaseModel {
+  static tablename = tableNameFor("ItemModel");
+  name = column.text().notNull();
+  price = column.integer().notNull();
+}
+`,
+    "src/schemas/item.ts": `import { baseResponseSchema, z } from "tempest-express-sdk";
+
+/** Request payload to create an item. */
+export const itemCreateSchema = z
+  .object({
+    name: z.string().min(1).openapi({ description: "The item name." }),
+    price: z.number().int().min(0).openapi({ description: "Price in cents." }),
+  })
+  .openapi("ItemCreate");
+
+/** Response payload for an item (base columns + domain fields). */
+export const itemResponseSchema = baseResponseSchema
+  .extend({
+    name: z.string(),
+    price: z.number().int(),
+  })
+  .openapi("Item");
+
+export type ItemCreate = z.infer<typeof itemCreateSchema>;
+export type ItemResponse = z.infer<typeof itemResponseSchema>;
+`,
+    "src/db/repositories/itemRepository.ts": `import { type AsyncSession, BaseRepository } from "tempest-express-sdk";
+import { ItemModel } from "@/db/models/itemModel";
+
+/** Data-access layer for items. */
+export class ItemRepository extends BaseRepository<typeof ItemModel> {
+  constructor(session: AsyncSession) {
+    super(ItemModel, session);
+  }
+}
+`,
+    "src/services/itemService.ts": `import { BaseService } from "tempest-express-sdk";
+import type { ItemRepository } from "@/db/repositories/itemRepository";
+import type { ItemModel } from "@/db/models/itemModel";
+import type { ItemResponse } from "@/schemas/item";
+
+/** Business logic for items. Maps raw rows to the response shape. */
+export class ItemService extends BaseService<typeof ItemModel, ItemResponse> {
+  constructor(repository: ItemRepository) {
+    super(repository, (row) => ({
+      id: row.id,
+      isActive: row.isActive,
+      createdAt: row.createdAt,
+      updatedAt: row.updatedAt,
+      name: row.name,
+      price: row.price,
+    }));
+  }
+}
+`,
+    "src/controllers/itemController.ts": `import { BaseController } from "tempest-express-sdk";
+import type { ItemModel } from "@/db/models/itemModel";
+import type { ItemResponse } from "@/schemas/item";
+import type { ItemService } from "@/services/itemService";
+
+/** Orchestration boundary between the router and the item service. */
+export class ItemController extends BaseController<typeof ItemModel, ItemResponse> {
+  constructor(service: ItemService) {
+    super(service);
+  }
+}
+`,
+    "src/api/routers/items.ts": `import { Router } from "express";
+import type { OpenAPIRegistry } from "tempest-express-sdk";
+import { itemCreateSchema, itemResponseSchema } from "@/schemas/item";
+
+/**
+ * Build the items router and register its OpenAPI paths.
+ *
+ * NOTE: wire a real controller (with a DB session) here. This stub returns
+ * static data so a freshly generated project boots without a database.
+ */
+export function makeItemsRouter(registry: OpenAPIRegistry): Router {
+  const router = Router();
+
+  registry.registerPath({
+    method: "get",
+    path: "/api/items",
+    summary: "List items",
+    responses: {
+      200: {
+        description: "The items",
+        content: { "application/json": { schema: itemResponseSchema.array() } },
+      },
+    },
+  });
+
+  registry.registerPath({
+    method: "post",
+    path: "/api/items",
+    summary: "Create an item",
+    request: {
+      body: { content: { "application/json": { schema: itemCreateSchema } } },
+    },
+    responses: {
+      201: {
+        description: "The created item",
+        content: { "application/json": { schema: itemResponseSchema } },
+      },
+    },
+  });
+
+  router.get("/api/items", (_req, res) => {
+    res.json([]);
+  });
+
+  router.post("/api/items", (req, res) => {
+    const data = itemCreateSchema.parse(req.body);
+    res.status(201).json({
+      id: "00000000-0000-0000-0000-000000000000",
+      isActive: true,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+      ...data,
+    });
+  });
+
+  return router;
+}
+`,
+    "src/api/app.ts": `import type { Express } from "express";
+import { createApp, createOpenApiRegistry } from "tempest-express-sdk";
+import { settings } from "@/core/settings";
+import { makeItemsRouter } from "@/api/routers/items";
+
+/** Build the configured Express application. */
+export async function makeApp(): Promise<Express> {
+  const registry = createOpenApiRegistry();
+
+  return createApp({
+    corsOrigins: settings.CORS_ORIGINS,
+    openapi: {
+      registry,
+      info: { title: "${name}", version: "0.1.0", description: "Powered by tempest-express-sdk." },
+    },
+    configure: (app) => {
+      app.use(makeItemsRouter(registry));
+    },
+  });
+}
+`,
+    "src/server.ts": `import { runServer } from "tempest-express-sdk";
+import { settings } from "@/core/settings";
+import { makeApp } from "@/api/app";
+
+/** Build the app and start listening. */
+export async function run(): Promise<void> {
+  const app = await makeApp();
+  await runServer(app, { host: settings.HOST, port: settings.PORT });
+}
+`,
+    "docker-compose.yml": dockerComposeFile(name),
+    "README.md": `# ${name}
+
+Generated with \`tempest-express new\` \u2014 an Express + Zod + tempest-db-js service.
+
+## Develop
+
+\`\`\`bash
+npm install
+cp .env.example .env
+npm run dev
+\`\`\`
+
+- API: http://127.0.0.1:8000/api/items
+- Swagger UI: http://127.0.0.1:8000/docs
+- Redoc: http://127.0.0.1:8000/redoc
+- Health: http://127.0.0.1:8000/health
+\`\`\`
+`
+  };
+}
+function toCamel(name) {
+  return name.charAt(0).toLowerCase() + name.slice(1);
+}
+function toSnake(name) {
+  return name.replace(/(?<!^)(?=[A-Z])/g, "_").toLowerCase();
+}
+function resourceFiles(pascal) {
+  const camel = toCamel(pascal);
+  const table = toSnake(pascal);
+  return {
+    [`src/db/models/${camel}Model.ts`]: `import { BaseModel, column, tableNameFor } from "tempest-express-sdk";
+
+/** The ${pascal} domain model. */
+export class ${pascal}Model extends BaseModel {
+  static tablename = tableNameFor("${pascal}Model"); // "${table}"
+  name = column.text().notNull();
+}
+`,
+    [`src/schemas/${camel}.ts`]: `import { baseResponseSchema, z } from "tempest-express-sdk";
+
+/** Request payload to create a ${pascal}. */
+export const ${camel}CreateSchema = z
+  .object({ name: z.string().min(1) })
+  .openapi("${pascal}Create");
+
+/** Response payload for a ${pascal}. */
+export const ${camel}ResponseSchema = baseResponseSchema
+  .extend({ name: z.string() })
+  .openapi("${pascal}");
+
+export type ${pascal}Create = z.infer<typeof ${camel}CreateSchema>;
+export type ${pascal}Response = z.infer<typeof ${camel}ResponseSchema>;
+`,
+    [`src/db/repositories/${camel}Repository.ts`]: `import { type AsyncSession, BaseRepository } from "tempest-express-sdk";
+import { ${pascal}Model } from "@/db/models/${camel}Model";
+
+/** Data-access layer for ${pascal}. */
+export class ${pascal}Repository extends BaseRepository<typeof ${pascal}Model> {
+  constructor(session: AsyncSession) {
+    super(${pascal}Model, session);
+  }
+}
+`,
+    [`src/services/${camel}Service.ts`]: `import { BaseService } from "tempest-express-sdk";
+import type { ${pascal}Model } from "@/db/models/${camel}Model";
+import type { ${pascal}Repository } from "@/db/repositories/${camel}Repository";
+import type { ${pascal}Response } from "@/schemas/${camel}";
+
+/** Business logic for ${pascal}. */
+export class ${pascal}Service extends BaseService<typeof ${pascal}Model, ${pascal}Response> {
+  constructor(repository: ${pascal}Repository) {
+    super(repository, (row) => ({
+      id: row.id,
+      isActive: row.isActive,
+      createdAt: row.createdAt,
+      updatedAt: row.updatedAt,
+      name: row.name,
+    }));
+  }
+}
+`,
+    [`src/controllers/${camel}Controller.ts`]: `import { BaseController } from "tempest-express-sdk";
+import type { ${pascal}Model } from "@/db/models/${camel}Model";
+import type { ${pascal}Response } from "@/schemas/${camel}";
+import type { ${pascal}Service } from "@/services/${camel}Service";
+
+/** Orchestration boundary for ${pascal}. */
+export class ${pascal}Controller extends BaseController<typeof ${pascal}Model, ${pascal}Response> {
+  constructor(service: ${pascal}Service) {
+    super(service);
+  }
+}
+`,
+    [`src/api/routers/${camel}s.ts`]: `import { Router } from "express";
+import type { OpenAPIRegistry } from "tempest-express-sdk";
+import { ${camel}CreateSchema, ${camel}ResponseSchema } from "@/schemas/${camel}";
+
+/** Build the ${pascal} router and register its OpenAPI paths. */
+export function make${pascal}sRouter(registry: OpenAPIRegistry): Router {
+  const router = Router();
+
+  registry.registerPath({
+    method: "get",
+    path: "/api/${camel}s",
+    summary: "List ${camel}s",
+    responses: {
+      200: {
+        description: "OK",
+        content: { "application/json": { schema: ${camel}ResponseSchema.array() } },
+      },
+    },
+  });
+  registry.registerPath({
+    method: "post",
+    path: "/api/${camel}s",
+    summary: "Create a ${camel}",
+    request: {
+      body: { content: { "application/json": { schema: ${camel}CreateSchema } } },
+    },
+    responses: {
+      201: {
+        description: "Created",
+        content: { "application/json": { schema: ${camel}ResponseSchema } },
+      },
+    },
+  });
+
+  router.get("/api/${camel}s", (_req, res) => res.json([]));
+  router.post("/api/${camel}s", (req, res) => {
+    const data = ${camel}CreateSchema.parse(req.body);
+    res.status(201).json({
+      id: "00000000-0000-0000-0000-000000000000",
+      isActive: true,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+      ...data,
+    });
+  });
+
+  return router;
+}
+`
+  };
+}
+function dockerComposeFile(name) {
+  return `services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: ${name}
+      POSTGRES_PASSWORD: ${name}
+      POSTGRES_DB: ${name}
+    ports:
+      - "5432:5432"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+
+volumes:
+  pgdata:
+`;
+}
+
+// src/version.ts
+var VERSION = "0.1.0";
+
+// src/cli/index.ts
+var USAGE = `tempest-express \u2014 Express SDK CLI
+
+Usage:
+  tempest-express new <name> [--dir <path>]        Scaffold a new service
+  tempest-express generate <Name> [--dir <path>]   Scaffold a CRUD resource
+  tempest-express secret [--bytes <n>]             Print a random secret
+  tempest-express docker-compose [--dir <path>]    Write a docker-compose.yml
+  tempest-express db                               Migration guidance
+  tempest-express --version                        Print the version
+  tempest-express --help                           Show this help
+`;
+var DB_HELP = `Migrations are handled by tempest-db-js (programmatic API):
+
+  import { ... } from "tempest-db-js/migrations";
+
+See https://www.npmjs.com/package/tempest-db-js for the migration workflow.
+`;
+async function writeFiles(root, files) {
+  for (const [relative, contents] of Object.entries(files)) {
+    const target = path.join(root, relative);
+    await promises.mkdir(path.dirname(target), { recursive: true });
+    await promises.writeFile(target, contents, "utf8");
+  }
+}
+async function runNew(name, dir) {
+  if (!/^[a-z0-9][a-z0-9-_]*$/i.test(name)) {
+    throw new Error(`Invalid project name: ${JSON.stringify(name)}`);
+  }
+  const root = path.resolve(dir, name);
+  await writeFiles(root, projectFiles(name));
+  process.stdout.write(
+    `Created ${name} at ${root}
+
+Next steps:
+  cd ${name}
+  npm install
+  cp .env.example .env
+  npm run dev
+`
+  );
+}
+async function runGenerate(name, dir) {
+  if (!/^[A-Z][A-Za-z0-9]*$/.test(name)) {
+    throw new Error(`Resource name must be PascalCase, got ${JSON.stringify(name)}`);
+  }
+  const files = resourceFiles(name);
+  await writeFiles(path.resolve(dir), files);
+  const written = Object.keys(files).map((path) => `  ${path}`).join("\n");
+  process.stdout.write(`Generated ${name} resource:
+${written}
+`);
+}
+async function main(argv = process.argv.slice(2)) {
+  const { values, positionals } = util.parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      version: { type: "boolean", short: "v" },
+      help: { type: "boolean", short: "h" },
+      dir: { type: "string", default: "." },
+      bytes: { type: "string", default: "32" }
+    }
+  });
+  if (values.version) {
+    process.stdout.write(`${VERSION}
+`);
+    return 0;
+  }
+  const [command, ...rest] = positionals;
+  if (values.help || command === void 0 || command === "help") {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  const dir = values.dir ?? ".";
+  if (command === "new") {
+    const name = rest[0];
+    if (!name) {
+      process.stderr.write(`error: \`new\` requires a project name
+
+${USAGE}`);
+      return 1;
+    }
+    await runNew(name, dir);
+    return 0;
+  }
+  if (command === "generate" || command === "g") {
+    const name = rest[0];
+    if (!name) {
+      process.stderr.write(`error: \`generate\` requires a resource name
+
+${USAGE}`);
+      return 1;
+    }
+    await runGenerate(name, dir);
+    return 0;
+  }
+  if (command === "secret") {
+    const nbytes = Number.parseInt(values.bytes ?? "32", 10);
+    if (!Number.isInteger(nbytes) || nbytes < 16) {
+      process.stderr.write("error: --bytes must be an integer >= 16\n");
+      return 1;
+    }
+    process.stdout.write(`${crypto.randomBytes(nbytes).toString("base64url")}
+`);
+    return 0;
+  }
+  if (command === "docker-compose") {
+    await writeFiles(path.resolve(dir), { "docker-compose.yml": dockerComposeFile("app") });
+    process.stdout.write(`Wrote ${path.resolve(dir, "docker-compose.yml")}
+`);
+    return 0;
+  }
+  if (command === "db") {
+    process.stdout.write(DB_HELP);
+    return 0;
+  }
+  process.stderr.write(`error: unknown command ${JSON.stringify(command)}
+
+${USAGE}`);
+  return 1;
+}
+main().then((code) => {
+  process.exitCode = code;
+}).catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`error: ${message}
+`);
+  process.exitCode = 1;
+});
+
+exports.main = main;
+//# sourceMappingURL=cli.cjs.map
+//# sourceMappingURL=cli.cjs.map