semola 0.5.1 → 0.5.3

package/README.md

@@ -18,15 +18,20 @@ Type-safe APIs, Redis queues, pub/sub, i18n, caching & auth with tree-shakeable
 
 ## ✨ Features
 
-| Module               | Description                                            | Import          |
-| -------------------- | ------------------------------------------------------ | --------------- |
-| **🚀 API Framework** | Type-safe REST API with OpenAPI & Bun-native routing   | `semola/api`    |
-| **📬 Queue**         | Redis-backed job queue with timeouts & concurrency     | `semola/queue`  |
-| **📡 PubSub**        | Type-safe Redis pub/sub for real-time messaging        | `semola/pubsub` |
-| **🔐 Policy**        | Policy-based authorization with type-safe guards       | `semola/policy` |
-| **🌍 i18n**          | Compile-time validated internationalization            | `semola/i18n`   |
-| **💾 Cache**         | Redis cache wrapper with TTL & automatic serialization | `semola/cache`  |
-| **⚠️ Errors**        | Result-based error handling without try/catch          | `semola/errors` |
+| Module               | Description                                            | Import            |
+| -------------------- | ------------------------------------------------------ | ----------------- |
+| **🚀 API Framework** | Type-safe REST API with OpenAPI & Bun-native routing   | `semola/api`      |
+| **📬 Queue**         | Redis-backed job queue with timeouts & concurrency     | `semola/queue`    |
+| **📡 PubSub**        | Type-safe Redis pub/sub for real-time messaging        | `semola/pubsub`   |
+| **🔐 Policy**        | Policy-based authorization with type-safe guards       | `semola/policy`   |
+| **🌍 i18n**          | Compile-time validated internationalization            | `semola/i18n`     |
+| **💾 Cache**         | Redis cache wrapper with TTL & automatic serialization | `semola/cache`    |
+| **⏰ Cron**          | In-memory cron scheduler for periodic task execution   | `semola/cron`     |
+| **🔁 Workflow**      | Durable resumable workflows with step persistence      | `semola/workflow` |
+| **⚠️ Errors**        | Result-based error handling without try/catch          | `semola/errors`   |
+| **📃 Logging**       | A simple logging utility                               | `semola/logging`  |
+| **⌨️ Prompts**       | Interactive zero-dependency CLI prompts                | `semola/prompts`  |
+| **🗄️ ORM**           | Type-safe data layer with query APIs + migrations      | `semola/orm`      |
 
 ---
 
@@ -81,6 +86,14 @@ if (error) {
 console.log("Success:", data);
 ```
 
+`mightThrow` and `mightThrowSync` default their error type to `Error`. If a promise or function can reject or throw non-Error values, pass a custom error generic.
+
+```typescript
+const [customError] = await mightThrow<never, { code: string }>(
+  Promise.reject({ code: "RATE_LIMITED" }),
+);
+```
+
 ### Process Background Jobs
 
 ```typescript
@@ -109,12 +122,16 @@ const pubsub = new PubSub({
 });
 
 // Subscribe to messages
-await pubsub.subscribe((message) => {
+const [, unsubscribeHandler] = await pubsub.subscribe((message) => {
   console.log("Received:", message);
 });
 
 // Publish a message
 await pubsub.publish({ userId: 123, text: "New alert!" });
+
+if (unsubscribeHandler) {
+  await unsubscribeHandler();
+}
 ```
 
 ### Cache Data with TTL
@@ -135,24 +152,108 @@ const [error, user] = await cache.get("user:123");
 if (!error) console.log(user);
 ```
 
+### Schedule Recurring Tasks
+
+```typescript
+import { Cron } from "semola/cron";
+
+const cleanup = new Cron({
+  name: "daily-cleanup",
+  schedule: "0 0 * * *", // Daily at midnight
+  handler: async () => {
+    await deleteOldLogs();
+    await archiveInactiveUsers();
+  },
+});
+
+cleanup.start();
+```
+
+### Query a Database
+
+```typescript
+import { createOrm, createTable, string, uuid } from "semola/orm";
+
+const users = createTable("users", {
+  id: uuid("id").primaryKey(),
+  name: string("name").notNull(),
+  email: string("email").unique().notNull(),
+});
+
+const db = createOrm({
+  url: "sqlite::memory:",
+  tables: { users },
+});
+
+// Result-pattern query
+const [findErr, rows] = await db.users.findMany({
+  where: { name: { contains: "John" } },
+  take: 10,
+});
+
+if (findErr) {
+  console.error(findErr.type, findErr.message);
+}
+
+// Create record (result pattern)
+const [createErr, user] = await db.users.create({
+  data: {
+    name: "John Doe",
+    email: "john@example.com",
+  },
+});
+
+// Low-level SQL-style methods are also available
+const insertedRows = await db.users.insert({
+  data: {
+    name: "Jane Doe",
+    email: "jane@example.com",
+  },
+  returning: true,
+});
+
+console.log(rows, user, createErr, insertedRows);
+```
+
+### Run ORM Migrations
+
+```bash
+# create migration from schema diff
+semola orm migrations create add-users
+
+# apply pending migrations
+semola orm migrations apply
+
+# rollback last applied migration
+semola orm migrations rollback
+```
+
 ### Check Permissions
 
 ```typescript
-import { Policy } from "semola/policy";
+import { Policy, eq, has } from "semola/policy";
+
+type User = { id: number; role: string; permissions: string[] };
 
-const policy = new Policy();
+const policy = new Policy<User>();
+
+// Allow admins full access
+policy.allow({
+  action: ["create", "update", "delete"],
+  conditions: { role: eq("admin") },
+  reason: "Admins have full access",
+});
 
-// Allow admins to edit any post
+// Allow users with a specific permission
 policy.allow({
-  action: "update",
-  entity: "post",
-  conditions: { role: "admin" },
-  reason: "Admins can edit any post",
+  action: "read",
+  conditions: { permissions: has("posts:read") },
 });
 
-// Check if user can edit
-const result = policy.can("update", "post", { role: user.role });
-console.log(result.allowed); // true or false
+// Check if user can perform an action
+const user: User = { id: 1, role: "admin", permissions: [] };
+const result = policy.can("update", user);
+console.log(result.allowed); // true
 ```
 
 ### Internationalize Your App
@@ -171,6 +272,15 @@ const i18n = new I18n({
 console.log(i18n.translate("greeting", { name: "World" }));
 ```
 
+### Log your messages
+
+```typescript
+import { ConsoleProvider, Logger } from "semola/logging";
+
+const logger = new Logger("database", [new ConsoleProvider()]);
+logger.info("Hello!");
+```
+
 ---
 
 ## 📦 Installation
@@ -206,14 +316,14 @@ Stop piecing together half-baked solutions from npm. Stop wrestling with type de
 
 Semola API is the **fastest API framework** for Bun.
 
-| Framework  | Avg Req/Sec | Latency Avg (ms) |   vs Semola   |
-| :--------- | ----------: | ---------------: | :-----------: |
-| **Semola** |  **40,050** |         **1.88** | **baseline**  |
-| Elysia     |      37,185 |             2.13 |  1.1x slower  |
-| Hono       |      34,611 |             2.31 |  1.2x slower  |
-| Fastify    |      26,330 |             3.70 |  1.5x slower  |
-| Express    |      20,031 |             5.02 | **2x slower** |
-| NestJS     |      16,118 |             6.21 |  2.5x slower  |
+| Framework  | Avg Req/Sec | Latency Avg (ms) |  vs Semola   |
+| :--------- | ----------: | ---------------: | :----------: |
+| **Semola** |  **40,050** |         **1.88** | **baseline** |
+| Elysia     |      37,185 |             2.13 | 1.1x slower  |
+| Hono       |      34,611 |             2.31 | 1.2x slower  |
+| Fastify    |      26,330 |             3.70 | 1.5x slower  |
+| Express    |      20,031 |             5.02 |  2x slower   |
+| NestJS     |      16,118 |             6.21 | 2.5x slower  |
 
 _Higher is better for req/sec, lower is better for latency._
 
@@ -234,10 +344,15 @@ _Higher is better for req/sec, lower is better for latency._
 - [API Framework](./docs/api.md) - Type-safe REST API framework with OpenAPI
 - [Queue](./docs/queue.md) - Redis-backed job queue with timeouts & concurrency
 - [PubSub](./docs/pubsub.md) - Type-safe Redis pub/sub
+- [Cron](./docs/cron.md) - In-memory cron scheduler for periodic task execution
+- [Workflow](./docs/workflow.md) - Durable and resumable workflows with step persistence
 - [Policy](./docs/policy.md) - Policy-based authorization
 - [i18n](./docs/i18n.md) - Type-safe internationalization
 - [Cache](./docs/cache.md) - Redis cache wrapper with TTL
 - [Errors](./docs/errors.md) - Result-based error handling
+- [Logging](./docs/logging.md) - Logging utility
+- [Prompts](./docs/prompts.md) - Interactive CLI prompts
+- [ORM](./docs/orm.md) - Type-safe data layer, result-pattern DX, and migrations
 
 ---
 
@@ -263,6 +378,6 @@ bun check
 
 This package uses GitHub Actions for automated publishing. To release:
 
-1. Bump version: `bun version <major|minor|patch>`
+1. Bump version: `bun pm version <major|minor|patch>`
 2. Create a GitHub release with a new tag (e.g., `v0.4.0`)
 3. The GitHub Action automatically publishes to npm with provenance

package/dist/api/core/index.cjs

@@ -0,0 +1,206 @@
+const require_lib_errors_index = require("../../lib/errors/index.cjs");
+const require_index = require("../openapi/index.cjs");
+const require_index$1 = require("../validation/index.cjs");
+//#region src/lib/api/core/index.ts
+const defaultValidated = Object.freeze({
+	body: void 0,
+	query: void 0,
+	headers: void 0,
+	cookies: void 0,
+	params: void 0
+});
+const responseHelpers = {
+	json: (status, data) => Response.json(data, { status }),
+	text: (status, text) => new Response(text, { status }),
+	html: (status, html) => new Response(html, {
+		status,
+		headers: { "Content-Type": "text/html" }
+	}),
+	redirect: (status, url) => Response.redirect(url, status)
+};
+const noopGet = () => void 0;
+const stripTrailingSlash = (path) => {
+	if (path !== "/" && path.endsWith("/")) return path.slice(0, -1);
+	return path;
+};
+const hasSchemas = (schema) => schema && (schema.body || schema.query || schema.headers || schema.cookies || schema.params);
+const needsBodyCache = (schema) => schema?.body !== void 0;
+const shouldCreateBodyCache = (hasMiddlewares, allMiddlewares, request) => {
+	if (needsBodyCache(request)) return true;
+	if (!hasMiddlewares) return false;
+	return allMiddlewares.some((mw) => needsBodyCache(mw.options.request));
+};
+const resolveValidation = (v) => {
+	if (v === void 0 || v === true) return {
+		input: true,
+		output: true
+	};
+	if (v === false) return {
+		input: false,
+		output: false
+	};
+	return {
+		input: v.input !== false,
+		output: v.output !== false
+	};
+};
+var Api = class {
+	options;
+	routes = [];
+	constructor(options = {}) {
+		this.options = options;
+	}
+	getFullPath(path) {
+		const normalizedPath = stripTrailingSlash(path) || "/";
+		if (!this.options.prefix) return normalizedPath;
+		const normalizedPrefix = stripTrailingSlash(this.options.prefix);
+		if (normalizedPrefix === "/") return normalizedPath;
+		if (normalizedPath === "/") return normalizedPrefix;
+		return normalizedPrefix + normalizedPath;
+	}
+	async validateRequestSchema(req, schema, bodyCache) {
+		if (!schema) return {
+			success: true,
+			data: {}
+		};
+		const v = {};
+		if (schema.body) {
+			const [err, val] = await require_index$1.validateBody(req, schema.body, bodyCache);
+			if (err) return {
+				success: false,
+				error: err
+			};
+			v.body = val;
+		}
+		if (schema.query) {
+			const [err, val] = await require_index$1.validateQuery(req, schema.query);
+			if (err) return {
+				success: false,
+				error: err
+			};
+			v.query = val;
+		}
+		if (schema.headers) {
+			const [err, val] = await require_index$1.validateHeaders(req, schema.headers);
+			if (err) return {
+				success: false,
+				error: err
+			};
+			v.headers = val;
+		}
+		if (schema.cookies) {
+			const [err, val] = await require_index$1.validateCookies(req, schema.cookies);
+			if (err) return {
+				success: false,
+				error: err
+			};
+			v.cookies = val;
+		}
+		if (schema.params) {
+			const [err, val] = await require_index$1.validateParams(req, schema.params);
+			if (err) return {
+				success: false,
+				error: err
+			};
+			v.params = val;
+		}
+		return {
+			success: true,
+			data: v
+		};
+	}
+	createContext(req, validated, extensions) {
+		return {
+			raw: req,
+			req: validated,
+			...responseHelpers,
+			get: (key) => extensions[key]
+		};
+	}
+	async validateResponseBody(response, schema) {
+		if (!schema) return response;
+		const statusSchema = schema[response.status];
+		if (!statusSchema) return response;
+		if (!(response.headers.get("content-type") ?? "").includes("application/json")) return response;
+		const [parseError, body] = await require_lib_errors_index.mightThrow(response.clone().json());
+		if (parseError) return responseHelpers.json(400, { message: "Invalid response body" });
+		const [validationError] = await require_index$1.validateSchema(statusSchema, body);
+		if (validationError) return responseHelpers.json(400, { message: validationError.message });
+		return response;
+	}
+	buildBunRoutes() {
+		const bunRoutes = {};
+		const validationConfig = resolveValidation(this.options.validation);
+		for (const route of this.routes) {
+			const { path, method, handler, request, response, middlewares } = route;
+			const fullPath = this.getFullPath(path);
+			if (!bunRoutes[fullPath]) bunRoutes[fullPath] = {};
+			const allMiddlewares = [...this.options.middlewares ?? [], ...middlewares ?? []];
+			const hasMiddlewares = allMiddlewares.length > 0;
+			const hasRouteSchemas = hasSchemas(request);
+			const effectiveOutputValidation = validationConfig.output && !!response;
+			if (!hasMiddlewares && !(validationConfig.input && hasRouteSchemas) && !effectiveOutputValidation) bunRoutes[fullPath][method] = (req) => {
+				const context = Object.create(responseHelpers);
+				context.raw = req;
+				context.req = defaultValidated;
+				context.get = noopGet;
+				return handler(context);
+			};
+			else bunRoutes[fullPath][method] = async (req) => {
+				const extensions = {};
+				const bodyCache = validationConfig.input && shouldCreateBodyCache(hasMiddlewares, allMiddlewares, request) ? {
+					parsed: false,
+					value: void 0
+				} : void 0;
+				for (const mw of allMiddlewares) {
+					const { request: reqSchema, handler: mwHandler } = mw.options;
+					let validated = defaultValidated;
+					if (validationConfig.input && hasSchemas(reqSchema)) {
+						const result = await this.validateRequestSchema(req, reqSchema, bodyCache);
+						if (!result.success) return responseHelpers.json(400, { message: result.error?.message });
+						validated = result.data;
+					}
+					const mwResult = await mwHandler(this.createContext(req, validated, extensions));
+					if (mwResult instanceof Response) return mwResult;
+					if (mwResult) Object.assign(extensions, mwResult);
+				}
+				let routeValidated = defaultValidated;
+				if (validationConfig.input && hasRouteSchemas) {
+					const result = await this.validateRequestSchema(req, request, bodyCache);
+					if (!result.success) return responseHelpers.json(400, { message: result.error?.message });
+					routeValidated = result.data;
+				}
+				const handlerResponse = await handler(this.createContext(req, routeValidated, extensions));
+				if (effectiveOutputValidation) return this.validateResponseBody(handlerResponse, response);
+				return handlerResponse;
+			};
+		}
+		return bunRoutes;
+	}
+	defineRoute(config) {
+		this.routes.push(config);
+	}
+	getOpenApiSpec() {
+		return require_index.generateOpenApiSpec({
+			title: this.options.openapi?.title ?? "API",
+			description: this.options.openapi?.description,
+			version: this.options.openapi?.version ?? "1.0.0",
+			prefix: this.options.prefix,
+			servers: this.options.openapi?.servers,
+			securitySchemes: this.options.openapi?.securitySchemes,
+			routes: this.routes,
+			globalMiddlewares: this.options.middlewares
+		});
+	}
+	serve(port, callback) {
+		const bunRoutes = this.buildBunRoutes();
+		const server = Bun.serve({
+			port,
+			routes: bunRoutes,
+			fetch: () => new Response("Not found", { status: 404 })
+		});
+		if (callback) callback(server);
+	}
+};
+//#endregion
+exports.Api = Api;

package/dist/api/core/index.d.cts

@@ -0,0 +1,21 @@
+import { OpenApiSpec } from "../openapi/types.cjs";
+import { ApiOptions, RequestSchema, ResponseSchema, RouteConfig } from "./types.cjs";
+import { Middleware } from "../middleware/index.cjs";
+
+//#region src/lib/api/core/index.d.ts
+declare class Api<TMiddlewares extends readonly Middleware[] = readonly []> {
+  private options;
+  private routes;
+  constructor(options?: ApiOptions<TMiddlewares>);
+  private getFullPath;
+  private validateRequestSchema;
+  private createContext;
+  private validateResponseBody;
+  private buildBunRoutes;
+  defineRoute<TReq extends RequestSchema = RequestSchema, TRes extends ResponseSchema = ResponseSchema, TRouteMiddlewares extends readonly Middleware[] = readonly []>(config: RouteConfig<TReq, TRes, TMiddlewares, TRouteMiddlewares>): void;
+  getOpenApiSpec(): Promise<OpenApiSpec>;
+  serve(port: number, callback?: (server: Bun.Server<unknown>) => void): void;
+}
+//#endregion
+export { Api };
+//# sourceMappingURL=index.d.cts.map

package/dist/api/core/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../../src/lib/api/core/index.ts"],"mappings":";;;;;cA4Ea,GAAA,+BAAkC,UAAA;EAAA,QACrC,OAAA;EAAA,QACA,MAAA;cAOW,OAAA,GAAS,UAAA,CAAW,YAAA;EAAA,QAI/B,WAAA;EAAA,QAaM,qBAAA;EAAA,QA+EN,aAAA;EAAA,QAaM,oBAAA;EAAA,QA6BN,cAAA;EAuHD,WAAA,cACQ,aAAA,GAAgB,aAAA,eAChB,cAAA,GAAiB,cAAA,qCACK,UAAA,iBAAA,CACnC,MAAA,EAAQ,WAAA,CAAY,IAAA,EAAM,IAAA,EAAM,YAAA,EAAc,iBAAA;EAWzC,cAAA,CAAA,GAAc,OAAA,CAXA,WAAA;EAwBd,KAAA,CAAM,IAAA,UAAc,QAAA,IAAY,MAAA,EAAQ,GAAA,CAAI,MAAA;AAAA"}

package/dist/api/core/index.d.mts

@@ -0,0 +1,21 @@
+import { OpenApiSpec } from "../openapi/types.mjs";
+import { ApiOptions, RequestSchema, ResponseSchema, RouteConfig } from "./types.mjs";
+import { Middleware } from "../middleware/index.mjs";
+
+//#region src/lib/api/core/index.d.ts
+declare class Api<TMiddlewares extends readonly Middleware[] = readonly []> {
+  private options;
+  private routes;
+  constructor(options?: ApiOptions<TMiddlewares>);
+  private getFullPath;
+  private validateRequestSchema;
+  private createContext;
+  private validateResponseBody;
+  private buildBunRoutes;
+  defineRoute<TReq extends RequestSchema = RequestSchema, TRes extends ResponseSchema = ResponseSchema, TRouteMiddlewares extends readonly Middleware[] = readonly []>(config: RouteConfig<TReq, TRes, TMiddlewares, TRouteMiddlewares>): void;
+  getOpenApiSpec(): Promise<OpenApiSpec>;
+  serve(port: number, callback?: (server: Bun.Server<unknown>) => void): void;
+}
+//#endregion
+export { Api };
+//# sourceMappingURL=index.d.mts.map

package/dist/api/core/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../../src/lib/api/core/index.ts"],"mappings":";;;;;cA4Ea,GAAA,+BAAkC,UAAA;EAAA,QACrC,OAAA;EAAA,QACA,MAAA;cAOW,OAAA,GAAS,UAAA,CAAW,YAAA;EAAA,QAI/B,WAAA;EAAA,QAaM,qBAAA;EAAA,QA+EN,aAAA;EAAA,QAaM,oBAAA;EAAA,QA6BN,cAAA;EAuHD,WAAA,cACQ,aAAA,GAAgB,aAAA,eAChB,cAAA,GAAiB,cAAA,qCACK,UAAA,iBAAA,CACnC,MAAA,EAAQ,WAAA,CAAY,IAAA,EAAM,IAAA,EAAM,YAAA,EAAc,iBAAA;EAWzC,cAAA,CAAA,GAAc,OAAA,CAXA,WAAA;EAwBd,KAAA,CAAM,IAAA,UAAc,QAAA,IAAY,MAAA,EAAQ,GAAA,CAAI,MAAA;AAAA"}