semola 0.5.2 → 0.5.3

package/README.md

@@ -18,18 +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`   |
-| **⏰ Cron**          | In-memory cron scheduler for periodic task execution   | `semola/cron`    |
-| **⚠️ 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` |
+| 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`      |
 
 ---
 
@@ -84,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
@@ -112,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
@@ -155,6 +169,65 @@ const cleanup = new Cron({
 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
@@ -272,12 +345,14 @@ _Higher is better for req/sec, lower is better for latency._
 - [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
 
 ---
 

package/dist/cron/builder/index.cjs

@@ -0,0 +1,166 @@
+//#region src/lib/cron/builder/index.ts
+const CRON_FIELD_ORDER = [
+	"second",
+	"minute",
+	"hour",
+	"day",
+	"month",
+	"weekday"
+];
+var FieldWrapper = class {
+	fields = [];
+	add(expr) {
+		this.fields.push(expr);
+	}
+	read() {
+		return this.fields;
+	}
+};
+var CronListBuilder = class {
+	wrapper;
+	constructor(wrapper) {
+		this.wrapper = wrapper;
+	}
+	any() {
+		this.wrapper.add({ type: "any" });
+		return this;
+	}
+	range(options) {
+		this.wrapper.add({
+			type: "range",
+			...options
+		});
+		return this;
+	}
+	step(options) {
+		this.wrapper.add({
+			type: "step",
+			...options
+		});
+		return this;
+	}
+	number(value) {
+		this.wrapper.add({
+			type: "value",
+			value
+		});
+		return this;
+	}
+};
+function range(options) {
+	return {
+		type: "range",
+		...options
+	};
+}
+function any() {
+	return { type: "any" };
+}
+function step(options) {
+	return {
+		type: "step",
+		...options
+	};
+}
+function list(builderFn) {
+	const wrapper = new FieldWrapper();
+	builderFn(new CronListBuilder(wrapper));
+	return {
+		type: "list",
+		values: wrapper.read()
+	};
+}
+function number(value) {
+	return {
+		type: "value",
+		value
+	};
+}
+function cronJobBuilder(buildFn) {
+	const fields = {
+		second: void 0,
+		minute: void 0,
+		hour: void 0,
+		day: void 0,
+		month: void 0,
+		weekday: void 0
+	};
+	const obj = {
+		second(expr) {
+			fields.second = checkExpr(expr);
+			return obj;
+		},
+		minute(expr) {
+			fields.minute = checkExpr(expr);
+			return obj;
+		},
+		hour(expr) {
+			fields.hour = checkExpr(expr);
+			return obj;
+		},
+		day(expr) {
+			fields.day = checkExpr(expr);
+			return obj;
+		},
+		month(expr) {
+			fields.month = checkExpr(expr);
+			return obj;
+		},
+		weekday(expr) {
+			fields.weekday = checkExpr(expr);
+			return obj;
+		}
+	};
+	buildFn(obj);
+	return generate(fields);
+}
+function checkExpr(expr) {
+	if (expr.type === "list") {
+		const { values } = expr;
+		if (values.length === 0) throw new Error("EmptyListError: List expression cannot be empty");
+		return values.map((e) => handleSimpleExpression(e)).join(",");
+	}
+	return handleSimpleExpression(expr);
+}
+function handleSimpleExpression(expr) {
+	switch (expr.type) {
+		case "any": return "*";
+		case "value": return `${expr.value}`;
+		case "range": {
+			const { min, max } = expr;
+			if (min > max) throw new Error(`OutOfBoundError: Expected ${min} <= ${max}`);
+			return `${min}-${max}`;
+		}
+		case "step": {
+			const { step, range } = expr;
+			if (step === 0) throw new Error(`OutOfBoundError: Expected step value greater than zero`);
+			if (!range) return `*/${step}`;
+			const { min, max } = range;
+			if (max === 0) {
+				if (min > max) throw new Error(`OutOfBoundError: Expected max value greater than zero`);
+				return `${min}-${max}/${step}`;
+			}
+			if (!max) return `${min}/${step}`;
+			if (min > max) throw new Error(`OutOfBoundError: Expected ${min} <= ${max}`);
+			return `${min}-${max}/${step}`;
+		}
+		default: return "*";
+	}
+}
+function generate(fields) {
+	const parts = [];
+	for (let index = 0; index < CRON_FIELD_ORDER.length; index++) {
+		const key = CRON_FIELD_ORDER[index];
+		if (!key) return "";
+		if (key === "second" && !fields[key]) continue;
+		parts.push(fields[key] ?? "*");
+	}
+	return parts.join(" ");
+}
+//#endregion
+exports.any = any;
+exports.cronJobBuilder = cronJobBuilder;
+exports.list = list;
+exports.number = number;
+exports.range = range;
+exports.step = step;

package/dist/cron/builder/index.d.cts

@@ -0,0 +1,28 @@
+import { BuilderFn, CronExpr, CronListExpr, CronRange, CronStep } from "./types.cjs";
+
+//#region src/lib/cron/builder/index.d.ts
+declare class FieldWrapper<T> {
+  private fields;
+  add(expr: CronListExpr<T>): void;
+  read(): CronListExpr<T>[];
+}
+declare class CronListBuilder<T> {
+  private wrapper;
+  constructor(wrapper: FieldWrapper<T>);
+  any(): CronListBuilder<T>;
+  range(options: CronRange<T>): CronListBuilder<T>;
+  step(options: CronStep<T>): CronListBuilder<T>;
+  number(value: T): CronListBuilder<T>;
+}
+declare function range<T>(options: CronRange<T>): CronExpr<T>;
+declare function any<T>(): CronExpr<T>;
+declare function step<T>(options: CronStep<T>): CronExpr<T>;
+declare function list<T>(builderFn: (builder: CronListBuilder<T>) => CronListBuilder<T>): CronExpr<T>;
+declare function number<T>(value: T): {
+  type: "value";
+  value: T;
+};
+declare function cronJobBuilder(buildFn: BuilderFn): string;
+//#endregion
+export { any, cronJobBuilder, list, number, range, step };
+//# sourceMappingURL=index.d.cts.map

package/dist/cron/builder/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../../src/lib/cron/builder/index.ts"],"mappings":";;;cAwBM,YAAA;EAAA,QACI,MAAA;EAED,GAAA,CAAI,IAAA,EAAM,YAAA,CAAa,CAAA;EAIvB,IAAA,CAAA,GAAI,YAAA,CAAA,CAAA;AAAA;AAAA,cAKP,eAAA;EAAA,QACI,OAAA;cAEW,OAAA,EAAS,YAAA,CAAa,CAAA;EAIlC,GAAA,CAAA,GAAO,eAAA,CAAgB,CAAA;EAKvB,KAAA,CAAM,OAAA,EAAS,SAAA,CAAU,CAAA,IAAK,eAAA,CAAgB,CAAA;EAK9C,IAAA,CAAK,OAAA,EAAS,QAAA,CAAS,CAAA,IAAK,eAAA,CAAgB,CAAA;EAK5C,MAAA,CAAO,KAAA,EAAO,CAAA,GAAI,eAAA,CAAgB,CAAA;AAAA;AAAA,iBAM3B,KAAA,GAAA,CAAS,OAAA,EAAS,SAAA,CAAU,CAAA,IAAK,QAAA,CAAS,CAAA;AAAA,iBAI1C,GAAA,GAAA,CAAA,GAAU,QAAA,CAAS,CAAA;AAAA,iBAInB,IAAA,GAAA,CAAQ,OAAA,EAAS,QAAA,CAAS,CAAA,IAAK,QAAA,CAAS,CAAA;AAAA,iBAIxC,IAAA,GAAA,CACd,SAAA,GAAY,OAAA,EAAS,eAAA,CAAgB,CAAA,MAAO,eAAA,CAAgB,CAAA,IAC3D,QAAA,CAAS,CAAA;AAAA,iBAOI,MAAA,GAAA,CAAU,KAAA,EAAO,CAAA;;SAAA,CAAA;AAAA;AAAA,iBAIjB,cAAA,CAAe,OAAA,EAAS,SAAA"}

package/dist/cron/builder/index.d.mts

@@ -0,0 +1,28 @@
+import { BuilderFn, CronExpr, CronListExpr, CronRange, CronStep } from "./types.mjs";
+
+//#region src/lib/cron/builder/index.d.ts
+declare class FieldWrapper<T> {
+  private fields;
+  add(expr: CronListExpr<T>): void;
+  read(): CronListExpr<T>[];
+}
+declare class CronListBuilder<T> {
+  private wrapper;
+  constructor(wrapper: FieldWrapper<T>);
+  any(): CronListBuilder<T>;
+  range(options: CronRange<T>): CronListBuilder<T>;
+  step(options: CronStep<T>): CronListBuilder<T>;
+  number(value: T): CronListBuilder<T>;
+}
+declare function range<T>(options: CronRange<T>): CronExpr<T>;
+declare function any<T>(): CronExpr<T>;
+declare function step<T>(options: CronStep<T>): CronExpr<T>;
+declare function list<T>(builderFn: (builder: CronListBuilder<T>) => CronListBuilder<T>): CronExpr<T>;
+declare function number<T>(value: T): {
+  type: "value";
+  value: T;
+};
+declare function cronJobBuilder(buildFn: BuilderFn): string;
+//#endregion
+export { any, cronJobBuilder, list, number, range, step };
+//# sourceMappingURL=index.d.mts.map

package/dist/cron/builder/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../../src/lib/cron/builder/index.ts"],"mappings":";;;cAwBM,YAAA;EAAA,QACI,MAAA;EAED,GAAA,CAAI,IAAA,EAAM,YAAA,CAAa,CAAA;EAIvB,IAAA,CAAA,GAAI,YAAA,CAAA,CAAA;AAAA;AAAA,cAKP,eAAA;EAAA,QACI,OAAA;cAEW,OAAA,EAAS,YAAA,CAAa,CAAA;EAIlC,GAAA,CAAA,GAAO,eAAA,CAAgB,CAAA;EAKvB,KAAA,CAAM,OAAA,EAAS,SAAA,CAAU,CAAA,IAAK,eAAA,CAAgB,CAAA;EAK9C,IAAA,CAAK,OAAA,EAAS,QAAA,CAAS,CAAA,IAAK,eAAA,CAAgB,CAAA;EAK5C,MAAA,CAAO,KAAA,EAAO,CAAA,GAAI,eAAA,CAAgB,CAAA;AAAA;AAAA,iBAM3B,KAAA,GAAA,CAAS,OAAA,EAAS,SAAA,CAAU,CAAA,IAAK,QAAA,CAAS,CAAA;AAAA,iBAI1C,GAAA,GAAA,CAAA,GAAU,QAAA,CAAS,CAAA;AAAA,iBAInB,IAAA,GAAA,CAAQ,OAAA,EAAS,QAAA,CAAS,CAAA,IAAK,QAAA,CAAS,CAAA;AAAA,iBAIxC,IAAA,GAAA,CACd,SAAA,GAAY,OAAA,EAAS,eAAA,CAAgB,CAAA,MAAO,eAAA,CAAgB,CAAA,IAC3D,QAAA,CAAS,CAAA;AAAA,iBAOI,MAAA,GAAA,CAAU,KAAA,EAAO,CAAA;;SAAA,CAAA;AAAA;AAAA,iBAIjB,cAAA,CAAe,OAAA,EAAS,SAAA"}

package/dist/cron/builder/index.mjs

@@ -0,0 +1,163 @@
+//#region src/lib/cron/builder/index.ts
+const CRON_FIELD_ORDER = [
+	"second",
+	"minute",
+	"hour",
+	"day",
+	"month",
+	"weekday"
+];
+var FieldWrapper = class {
+	fields = [];
+	add(expr) {
+		this.fields.push(expr);
+	}
+	read() {
+		return this.fields;
+	}
+};
+var CronListBuilder = class {
+	wrapper;
+	constructor(wrapper) {
+		this.wrapper = wrapper;
+	}
+	any() {
+		this.wrapper.add({ type: "any" });
+		return this;
+	}
+	range(options) {
+		this.wrapper.add({
+			type: "range",
+			...options
+		});
+		return this;
+	}
+	step(options) {
+		this.wrapper.add({
+			type: "step",
+			...options
+		});
+		return this;
+	}
+	number(value) {
+		this.wrapper.add({
+			type: "value",
+			value
+		});
+		return this;
+	}
+};
+function range(options) {
+	return {
+		type: "range",
+		...options
+	};
+}
+function any() {
+	return { type: "any" };
+}
+function step(options) {
+	return {
+		type: "step",
+		...options
+	};
+}
+function list(builderFn) {
+	const wrapper = new FieldWrapper();
+	builderFn(new CronListBuilder(wrapper));
+	return {
+		type: "list",
+		values: wrapper.read()
+	};
+}
+function number(value) {
+	return {
+		type: "value",
+		value
+	};
+}
+function cronJobBuilder(buildFn) {
+	const fields = {
+		second: void 0,
+		minute: void 0,
+		hour: void 0,
+		day: void 0,
+		month: void 0,
+		weekday: void 0
+	};
+	const obj = {
+		second(expr) {
+			fields.second = checkExpr(expr);
+			return obj;
+		},
+		minute(expr) {
+			fields.minute = checkExpr(expr);
+			return obj;
+		},
+		hour(expr) {
+			fields.hour = checkExpr(expr);
+			return obj;
+		},
+		day(expr) {
+			fields.day = checkExpr(expr);
+			return obj;
+		},
+		month(expr) {
+			fields.month = checkExpr(expr);
+			return obj;
+		},
+		weekday(expr) {
+			fields.weekday = checkExpr(expr);
+			return obj;
+		}
+	};
+	buildFn(obj);
+	return generate(fields);
+}
+function checkExpr(expr) {
+	if (expr.type === "list") {
+		const { values } = expr;
+		if (values.length === 0) throw new Error("EmptyListError: List expression cannot be empty");
+		return values.map((e) => handleSimpleExpression(e)).join(",");
+	}
+	return handleSimpleExpression(expr);
+}
+function handleSimpleExpression(expr) {
+	switch (expr.type) {
+		case "any": return "*";
+		case "value": return `${expr.value}`;
+		case "range": {
+			const { min, max } = expr;
+			if (min > max) throw new Error(`OutOfBoundError: Expected ${min} <= ${max}`);
+			return `${min}-${max}`;
+		}
+		case "step": {
+			const { step, range } = expr;
+			if (step === 0) throw new Error(`OutOfBoundError: Expected step value greater than zero`);
+			if (!range) return `*/${step}`;
+			const { min, max } = range;
+			if (max === 0) {
+				if (min > max) throw new Error(`OutOfBoundError: Expected max value greater than zero`);
+				return `${min}-${max}/${step}`;
+			}
+			if (!max) return `${min}/${step}`;
+			if (min > max) throw new Error(`OutOfBoundError: Expected ${min} <= ${max}`);
+			return `${min}-${max}/${step}`;
+		}
+		default: return "*";
+	}
+}
+function generate(fields) {
+	const parts = [];
+	for (let index = 0; index < CRON_FIELD_ORDER.length; index++) {
+		const key = CRON_FIELD_ORDER[index];
+		if (!key) return "";
+		if (key === "second" && !fields[key]) continue;
+		parts.push(fields[key] ?? "*");
+	}
+	return parts.join(" ");
+}
+//#endregion
+export { any, cronJobBuilder, list, number, range, step };
+
+//# sourceMappingURL=index.mjs.map

package/dist/cron/builder/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../src/lib/cron/builder/index.ts"],"sourcesContent":["import type {\n  BuilderFn,\n  CronBuilderType,\n  CronExpr,\n  CronField,\n  CronListExpr,\n  CronRange,\n  CronStep,\n  DayType,\n  HourType,\n  MonthType,\n  TimeType,\n  WeekDayType,\n} from \"./types.js\";\n\nconst CRON_FIELD_ORDER: CronField[] = [\n  \"second\",\n  \"minute\",\n  \"hour\",\n  \"day\",\n  \"month\",\n  \"weekday\",\n] as const;\n\nclass FieldWrapper<T> {\n  private fields: CronListExpr<T>[] = [];\n\n  public add(expr: CronListExpr<T>) {\n    this.fields.push(expr);\n  }\n\n  public read() {\n    return this.fields;\n  }\n}\n\nclass CronListBuilder<T> {\n  private wrapper: FieldWrapper<T>;\n\n  public constructor(wrapper: FieldWrapper<T>) {\n    this.wrapper = wrapper;\n  }\n\n  public any(): CronListBuilder<T> {\n    this.wrapper.add({ type: \"any\" });\n    return this;\n  }\n\n  public range(options: CronRange<T>): CronListBuilder<T> {\n    this.wrapper.add({ type: \"range\", ...options });\n    return this;\n  }\n\n  public step(options: CronStep<T>): CronListBuilder<T> {\n    this.wrapper.add({ type: \"step\", ...options });\n    return this;\n  }\n\n  public number(value: T): CronListBuilder<T> {\n    this.wrapper.add({ type: \"value\", value: value });\n    return this;\n  }\n}\n\nexport function range<T>(options: CronRange<T>): CronExpr<T> {\n  return { type: \"range\", ...options };\n}\n\nexport function any<T>(): CronExpr<T> {\n  return { type: \"any\" };\n}\n\nexport function step<T>(options: CronStep<T>): CronExpr<T> {\n  return { type: \"step\", ...options };\n}\n\nexport function list<T>(\n  builderFn: (builder: CronListBuilder<T>) => CronListBuilder<T>,\n): CronExpr<T> {\n  const wrapper = new FieldWrapper<T>();\n  builderFn(new CronListBuilder<T>(wrapper));\n\n  return { type: \"list\", values: wrapper.read() };\n}\n\nexport function number<T>(value: T) {\n  return { type: \"value\", value: value } satisfies CronExpr<T>;\n}\n\nexport function cronJobBuilder(buildFn: BuilderFn) {\n  const fields: Partial<Record<CronField, string>> = {\n    second: undefined,\n    minute: undefined,\n    hour: undefined,\n    day: undefined,\n    month: undefined,\n    weekday: undefined,\n  };\n\n  const obj: CronBuilderType = {\n    second(expr: CronExpr<TimeType>) {\n      fields.second = checkExpr(expr);\n      return obj;\n    },\n    minute(expr: CronExpr<TimeType>) {\n      fields.minute = checkExpr(expr);\n      return obj;\n    },\n    hour(expr: CronExpr<HourType>) {\n      fields.hour = checkExpr(expr);\n      return obj;\n    },\n    day(expr: CronExpr<DayType>) {\n      fields.day = checkExpr(expr);\n      return obj;\n    },\n    month(expr: CronExpr<MonthType>) {\n      fields.month = checkExpr(expr);\n      return obj;\n    },\n    weekday(expr: CronExpr<WeekDayType>) {\n      fields.weekday = checkExpr(expr);\n      return obj;\n    },\n  };\n\n  buildFn(obj);\n  return generate(fields);\n}\n\nfunction checkExpr<T>(expr: CronExpr<T>) {\n  if (expr.type === \"list\") {\n    const { values } = expr;\n    if (values.length === 0) {\n      throw new Error(\"EmptyListError: List expression cannot be empty\");\n    }\n\n    const data = values.map((e) => handleSimpleExpression(e));\n\n    return data.join(\",\");\n  }\n\n  return handleSimpleExpression(expr);\n}\n\nfunction handleSimpleExpression<T>(expr: CronExpr<T>) {\n  switch (expr.type) {\n    case \"any\": {\n      return \"*\";\n    }\n\n    case \"value\": {\n      return `${expr.value}`;\n    }\n\n    case \"range\": {\n      const { min, max } = expr;\n      if (min > max) {\n        throw new Error(`OutOfBoundError: Expected ${min} <= ${max}`);\n      }\n\n      return `${min}-${max}`;\n    }\n\n    case \"step\": {\n      const { step, range } = expr;\n\n      if (step === 0) {\n        throw new Error(\n          `OutOfBoundError: Expected step value greater than zero`,\n        );\n      }\n\n      if (!range) {\n        return `*/${step}`;\n      }\n\n      const { min, max } = range;\n\n      if (max === 0) {\n        if (min > max) {\n          throw new Error(\n            `OutOfBoundError: Expected max value greater than zero`,\n          );\n        }\n\n        return `${min}-${max}/${step}`;\n      }\n\n      if (!max) {\n        return `${min}/${step}`;\n      }\n\n      if (min > max) {\n        throw new Error(`OutOfBoundError: Expected ${min} <= ${max}`);\n      }\n\n      return `${min}-${max}/${step}`;\n    }\n\n    default: {\n      return \"*\";\n    }\n  }\n}\n\nfunction generate(fields: Partial<Record<CronField, string>>): string {\n  const parts: string[] = [];\n\n  for (let index = 0; index < CRON_FIELD_ORDER.length; index++) {\n    const key = CRON_FIELD_ORDER[index];\n    if (!key) return \"\";\n    if (key === \"second\" && !fields[key]) {\n      continue;\n    }\n\n    parts.push(fields[key] ?? \"*\");\n  }\n\n  return parts.join(\" \");\n}\n"],"mappings":"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"}

package/dist/cron/builder/types.cjs

@@ -0,0 +1,27 @@
+//#region src/lib/cron/builder/types.ts
+const WeekDay = {
+	sun: 0,
+	mon: 1,
+	tue: 2,
+	wed: 3,
+	thu: 4,
+	fri: 5,
+	sat: 6
+};
+const Month = {
+	jan: 1,
+	feb: 2,
+	mar: 3,
+	apr: 4,
+	may: 5,
+	jun: 6,
+	jul: 7,
+	aug: 8,
+	sep: 9,
+	oct: 10,
+	nov: 11,
+	dec: 12
+};
+//#endregion
+exports.Month = Month;
+exports.WeekDay = WeekDay;

package/dist/cron/builder/types.d.cts

@@ -0,0 +1,79 @@
+//#region src/lib/cron/builder/types.d.ts
+declare const WeekDay: {
+  readonly sun: 0;
+  readonly mon: 1;
+  readonly tue: 2;
+  readonly wed: 3;
+  readonly thu: 4;
+  readonly fri: 5;
+  readonly sat: 6;
+};
+declare const Month: {
+  readonly jan: 1;
+  readonly feb: 2;
+  readonly mar: 3;
+  readonly apr: 4;
+  readonly may: 5;
+  readonly jun: 6;
+  readonly jul: 7;
+  readonly aug: 8;
+  readonly sep: 9;
+  readonly oct: 10;
+  readonly nov: 11;
+  readonly dec: 12;
+};
+type Enumerate<N extends number, Acc extends number[] = []> = Acc["length"] extends N ? Acc[number] : Enumerate<N, [...Acc, Acc["length"]]>;
+type IntRange<F extends number, T extends number> = Exclude<Enumerate<T>, Enumerate<F>>;
+type TimeType = IntRange<0, 60>;
+type HourType = IntRange<0, 24>;
+type DayType = IntRange<1, 32>;
+type MonthType = IntRange<1, 13>;
+type WeekDayType = IntRange<0, 7>;
+type CronRange<T> = {
+  min: NoInfer<T>;
+  max: NoInfer<T>;
+};
+type CronStep<T> = {
+  step: NoInfer<T>;
+  range?: {
+    min: NoInfer<T>;
+    max?: NoInfer<T>;
+  };
+};
+type CronField = "second" | "minute" | "hour" | "day" | "month" | "weekday";
+type CronListExpr<T> = Exclude<CronExpr<T>, {
+  type: "list";
+}>;
+type CronExpr<T> = {
+  type: "any";
+} | {
+  type: "value";
+  value: T;
+} | {
+  type: "range";
+  min: T;
+  max: T;
+} | {
+  type: "step";
+  step: T;
+  range?: {
+    min: T;
+    max?: T;
+  };
+} | {
+  type: "list";
+  values: CronListExpr<T>[];
+};
+interface IBuilder<Used extends CronField> {
+  second(expr: CronExpr<TimeType>): CronBuilderType<Used | "second">;
+  minute(expr: CronExpr<TimeType>): CronBuilderType<Used | "minute">;
+  hour(expr: CronExpr<HourType>): CronBuilderType<Used | "hour">;
+  day(expr: CronExpr<DayType>): CronBuilderType<Used | "day">;
+  month(expr: CronExpr<MonthType>): CronBuilderType<Used | "month">;
+  weekday(expr: CronExpr<WeekDayType>): CronBuilderType<Used | "weekday">;
+}
+type CronBuilderType<Used extends CronField = never> = Omit<IBuilder<Used>, Used>;
+type BuilderFn = (builder: CronBuilderType) => void;
+//#endregion
+export { BuilderFn, CronExpr, CronListExpr, CronRange, CronStep, Month, WeekDay };
+//# sourceMappingURL=types.d.cts.map

package/dist/cron/builder/types.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.cts","names":[],"sources":["../../../src/lib/cron/builder/types.ts"],"mappings":";cAAa,OAAA;EAAA;;;;;;;;cAUA,KAAA;EAAA;;;;;;;;;;;;;KAeR,SAAA,gDAGD,GAAA,mBAAsB,CAAA,GACtB,GAAA,WACA,SAAA,CAAU,CAAA,MAAO,GAAA,EAAK,GAAA;AAAA,KAErB,QAAA,uCAA+C,OAAA,CAClD,SAAA,CAAU,CAAA,GACV,SAAA,CAAU,CAAA;AAAA,KAGA,QAAA,GAAW,QAAA;AAAA,KACX,QAAA,GAAW,QAAA;AAAA,KACX,OAAA,GAAU,QAAA;AAAA,KACV,SAAA,GAAY,QAAA;AAAA,KACZ,WAAA,GAAc,QAAA;AAAA,KAEd,SAAA;EAAiB,GAAA,EAAK,OAAA,CAAQ,CAAA;EAAI,GAAA,EAAK,OAAA,CAAQ,CAAA;AAAA;AAAA,KAC/C,QAAA;EACV,IAAA,EAAM,OAAA,CAAQ,CAAA;EACd,KAAA;IAAU,GAAA,EAAK,OAAA,CAAQ,CAAA;IAAI,GAAA,GAAM,OAAA,CAAQ,CAAA;EAAA;AAAA;AAAA,KAG/B,SAAA;AAAA,KAQA,YAAA,MAAkB,OAAA,CAAQ,QAAA,CAAS,CAAA;EAAM,IAAA;AAAA;AAAA,KAEzC,QAAA;EACN,IAAA;AAAA;EACA,IAAA;EAAe,KAAA,EAAO,CAAA;AAAA;EACtB,IAAA;EAAe,GAAA,EAAK,CAAA;EAAG,GAAA,EAAK,CAAA;AAAA;EAC5B,IAAA;EAAc,IAAA,EAAM,CAAA;EAAG,KAAA;IAAU,GAAA,EAAK,CAAA;IAAG,GAAA,GAAM,CAAA;EAAA;AAAA;EAC/C,IAAA;EAAc,MAAA,EAAQ,YAAA,CAAa,CAAA;AAAA;AAAA,UAE/B,QAAA,cAAsB,SAAA;EAC9B,MAAA,CAAO,IAAA,EAAM,QAAA,CAAS,QAAA,IAAY,eAAA,CAAgB,IAAA;EAClD,MAAA,CAAO,IAAA,EAAM,QAAA,CAAS,QAAA,IAAY,eAAA,CAAgB,IAAA;EAClD,IAAA,CAAK,IAAA,EAAM,QAAA,CAAS,QAAA,IAAY,eAAA,CAAgB,IAAA;EAChD,GAAA,CAAI,IAAA,EAAM,QAAA,CAAS,OAAA,IAAW,eAAA,CAAgB,IAAA;EAC9C,KAAA,CAAM,IAAA,EAAM,QAAA,CAAS,SAAA,IAAa,eAAA,CAAgB,IAAA;EAClD,OAAA,CAAQ,IAAA,EAAM,QAAA,CAAS,WAAA,IAAe,eAAA,CAAgB,IAAA;AAAA;AAAA,KAG5C,eAAA,cAA6B,SAAA,YAAqB,IAAA,CAC5D,QAAA,CAAS,IAAA,GACT,IAAA;AAAA,KAGU,SAAA,IAAa,OAAA,EAAS,eAAA"}