syncorejs 0.2.1 → 0.2.3

package/dist/_vendor/core/runtime/functions.d.mts

@@ -1,12 +1,56 @@
 import { Infer, Validator, ValidatorMap } from "../../schema/index.d.ts";
 
 //#region src/runtime/functions.d.ts
+/**
+ * Discriminates the three function kinds Syncore supports.
+ *
+ * - `"query"` — read-only handler that observes local state. Syncore re-runs it
+ *   automatically whenever any table it read changes, keeping connected clients
+ *   up to date without manual cache invalidation.
+ * - `"mutation"` — transactional write handler. Runs inside a single SQLite
+ *   transaction and automatically invalidates every query that read the tables it
+ *   modified.
+ * - `"action"` — arbitrary async handler that may call external services, invoke
+ *   other Syncore functions, or schedule deferred work. Actions do not run inside
+ *   a transaction and cannot directly write to the database — they must delegate
+ *   writes to mutations.
+ */
 type SyncoreFunctionKind = "query" | "mutation" | "action";
+/**
+ * Convenience type representing a function that accepts no arguments.
+ *
+ * Used as the default `TArgs` for {@link FunctionReference} so that calling
+ * `client.query(api.tasks.list)` without a second argument is type-safe.
+ */
 type EmptyArgs = Record<never, never>;
 /**
- * A typed reference to a Syncore function.
+ * A typed, serialisable handle to a registered Syncore function.
+ *
+ * `FunctionReference` objects are how you address Syncore functions across the
+ * entire API surface: hooks, client calls, scheduler helpers, and `ctx.runQuery`
+ * / `ctx.runMutation` inside other functions all accept them. They carry the
+ * function's kind and its fully-inferred arg / result types at the type level,
+ * but at runtime they hold only the function's string name, making them safe to
+ * pass across IPC channels.
+ *
+ * In almost every case you get references from the auto-generated `api` object
+ * rather than constructing them manually:
+ *
+ * ```ts
+ * import { api } from "../syncore/_generated/api";
+ *
+ * // In a React component:
+ * const tasks = useQuery(api.tasks.list);
+ *
+ * // Inside a mutation that calls another function:
+ * const id = await ctx.runMutation(api.tasks.create, { title: "Buy milk" });
  *
- * Most app code gets these references from the generated `api` object.
+ * // Scheduling deferred work:
+ * await ctx.scheduler.runAfter(60_000, api.notifications.send, { userId });
+ * ```
+ *
+ * When you need to type a parameter that accepts a function reference, derive
+ * the correct type with {@link FunctionReferenceFor}.
  */
 interface FunctionReference<TKind extends SyncoreFunctionKind = SyncoreFunctionKind, TArgs = EmptyArgs, TResult = unknown> {
   kind: TKind;
@@ -14,36 +58,163 @@ interface FunctionReference<TKind extends SyncoreFunctionKind = SyncoreFunctionK
   readonly __args?: TArgs;
   readonly __result?: TResult;
 }
+/**
+ * The full definition of a Syncore function as produced by {@link query},
+ * {@link mutation}, or {@link action}.
+ *
+ * This is the value you export from files inside `syncore/functions/`. Syncore
+ * stores it in the function registry and uses the validators at runtime to parse
+ * incoming arguments and optionally validate return values.
+ *
+ * You rarely reference this type directly in application code — use
+ * {@link FunctionReferenceFor} when you need a type-level handle, or the
+ * generated `api` object for runtime usage.
+ */
 interface SyncoreFunctionDefinition<TKind extends SyncoreFunctionKind, TContext, TArgs, TResult> {
   kind: TKind;
-  argsValidator: Validator<TArgs>;
-  returnsValidator?: Validator<TResult>;
+  argsValidator: Validator<TArgs, TArgs, string>;
+  returnsValidator?: Validator<TResult, TResult, string>;
   handler: (ctx: TContext, args: TArgs) => Promise<TResult> | TResult;
 }
+/**
+ * Extracts the argument type from a {@link FunctionReference}.
+ *
+ * Useful when writing generic helpers that accept a function reference and need
+ * to type the corresponding arguments:
+ *
+ * ```ts
+ * async function run<TRef extends FunctionReference<"mutation">>(
+ *   ref: TRef,
+ *   args: FunctionArgs<TRef>
+ * ) { ... }
+ * ```
+ */
 type FunctionArgs<TReference> = TReference extends FunctionReference<SyncoreFunctionKind, infer TArgs, unknown> ? TArgs : never;
+/**
+ * Extracts the result type from a {@link FunctionReference}.
+ *
+ * ```ts
+ * type TaskList = FunctionResult<typeof api.tasks.list>; // Task[]
+ * ```
+ */
 type FunctionResult<TReference> = TReference extends FunctionReference<SyncoreFunctionKind, unknown, infer TResult> ? TResult : never;
+/**
+ * Extracts the {@link SyncoreFunctionKind} from a function definition object.
+ *
+ * Used internally by {@link FunctionReferenceFor} and the code generator.
+ */
 type FunctionKindFromDefinition<TDefinition> = TDefinition extends {
   kind: infer TKind;
 } ? Extract<TKind, SyncoreFunctionKind> : never;
+/**
+ * Extracts the validated argument type from a function definition object.
+ *
+ * Used internally by {@link FunctionReferenceFor} and the code generator.
+ */
 type FunctionArgsFromDefinition<TDefinition> = TDefinition extends {
-  argsValidator: Validator<infer TArgs>;
+  argsValidator: Validator<infer TArgs, unknown, string>;
 } ? TArgs : never;
+/**
+ * Extracts the return type from a function definition object.
+ *
+ * Used internally by {@link FunctionReferenceFor} and the code generator.
+ */
 type FunctionResultFromDefinition<TDefinition> = TDefinition extends {
-  returnsValidator?: Validator<infer TResult>;
+  returnsValidator?: Validator<infer TResult, unknown, string>;
 } ? TResult : never;
+/**
+ * Derives a fully-typed {@link FunctionReference} from a function definition.
+ *
+ * Use this when you need a typed reference to a function you have imported
+ * directly — for example when writing test helpers or custom wrappers:
+ *
+ * ```ts
+ * import type { create } from "../syncore/functions/tasks";
+ *
+ * type CreateRef = FunctionReferenceFor<typeof create>;
+ * // FunctionReference<"mutation", { title: string }, string>
+ * ```
+ *
+ * The generated `api` object already exposes `FunctionReferenceFor`-derived
+ * values for every exported function, so you rarely need this in application
+ * code.
+ */
 type FunctionReferenceFor<TDefinition> = FunctionKindFromDefinition<TDefinition> extends never ? never : FunctionReference<FunctionKindFromDefinition<TDefinition>, FunctionArgsFromDefinition<TDefinition>, FunctionResultFromDefinition<TDefinition>>;
+/**
+ * Configuration object accepted by {@link query}, {@link mutation}, and
+ * {@link action}.
+ *
+ * @template TContext - The execution context injected by the runtime
+ *   (`QueryCtx`, `MutationCtx`, or `ActionCtx`).
+ * @template TArgs   - The validated argument shape after parsing.
+ * @template TResult - The return type of the handler.
+ */
 interface FunctionConfig<TContext, TArgs, TResult> {
-  args: Validator<TArgs> | ValidatorMap;
-  returns?: Validator<TResult>;
+  /**
+   * Schema that validates and types the arguments this function accepts.
+   *
+   * You can pass either a single `Validator` or a plain object ("validator map")
+   * whose keys map to individual field validators — both forms are equivalent:
+   *
+   * ```ts
+   * // Validator map (most common)
+   * args: { title: s.string(), done: s.boolean() }
+   *
+   * // Single object validator (same result)
+   * args: s.object({ title: s.string(), done: s.boolean() })
+   * ```
+   */
+  args: Validator<TArgs, TArgs, string> | ValidatorMap;
+  /**
+   * Optional schema that validates the value returned by the handler.
+   *
+   * When provided, Syncore validates the return value before sending it to
+   * clients. Omitting `returns` disables return-value validation but does not
+   * affect the TypeScript return type inferred from the handler.
+   */
+  returns?: Validator<TResult, TResult, string>;
+  /**
+   * The function body. Receives a typed context object and the validated
+   * arguments and must return (or resolve to) the function's result.
+   */
   handler: (ctx: TContext, args: TArgs) => Promise<TResult> | TResult;
 }
-type InferArgs<TArgs extends Validator<unknown> | ValidatorMap> = TArgs extends Validator<unknown> ? Infer<TArgs> : TArgs extends ValidatorMap ? { [TKey in keyof TArgs]: Infer<TArgs[TKey]> } : never;
+type InferArgs<TArgs extends Validator<unknown, unknown, string> | ValidatorMap> = TArgs extends Validator<unknown, unknown, string> ? Infer<TArgs> : TArgs extends ValidatorMap ? { [TKey in keyof TArgs]: Infer<TArgs[TKey]> } : never;
 /**
  * Define a Syncore query.
  *
- * Queries can read local Syncore state and are available to clients.
+ * Queries are the read layer of Syncore. They run inside a read-only database
+ * transaction, may call other queries via `ctx.runQuery`, and are
+ * **automatically reactive**: whenever a table that a query read changes,
+ * every active subscription to that query is invalidated and re-executed.
+ *
+ * Export one query per named export in a file under `syncore/functions/`.
+ * After running `npx syncorejs codegen` a typed reference will be available
+ * on the generated `api` object.
+ *
+ * ```ts
+ * // syncore/functions/tasks.ts
+ * import { query } from "syncorejs";
+ * import { s } from "syncorejs";
+ * import type { QueryCtx } from "../_generated/server";
+ *
+ * export const list = query({
+ *   args: { projectId: s.optional(s.id("projects")) },
+ *   handler: async (ctx: QueryCtx, { projectId }) => {
+ *     return ctx.db
+ *       .query("tasks")
+ *       .withIndex("by_project", (q) =>
+ *         projectId ? q.eq("projectId", projectId) : q
+ *       )
+ *       .collect();
+ *   },
+ * });
+ * ```
+ *
+ * @param config - The {@link FunctionConfig} describing the args schema,
+ *   optional return-value schema, and handler function.
  */
-declare function query<TContext = unknown, TValidator extends Validator<unknown> = Validator<unknown>, TResult = unknown>(config: FunctionConfig<TContext, Infer<TValidator>, TResult> & {
+declare function query<TContext = unknown, TValidator extends Validator<unknown, unknown, string> = Validator<unknown, unknown, string>, TResult = unknown>(config: FunctionConfig<TContext, Infer<TValidator>, TResult> & {
   args: TValidator;
 }): SyncoreFunctionDefinition<"query", TContext, Infer<TValidator>, TResult>;
 declare function query<TContext = unknown, TArgsShape extends ValidatorMap = ValidatorMap, TResult = unknown>(config: FunctionConfig<TContext, InferArgs<TArgsShape>, TResult> & {
@@ -52,9 +223,38 @@ declare function query<TContext = unknown, TArgsShape extends ValidatorMap = Val
 /**
  * Define a Syncore mutation.
  *
- * Mutations can modify local Syncore state and are available to clients.
+ * Mutations are the write layer of Syncore. Every mutation runs inside an
+ * **atomic SQLite transaction**: if the handler throws, all writes are rolled
+ * back. After a successful commit Syncore automatically invalidates and
+ * re-executes every active query whose read-set overlaps the changed tables.
+ *
+ * Mutations receive a {@link MutationCtx}, which extends the query context
+ * with `ctx.db` write methods and a `ctx.scheduler` for scheduling deferred
+ * work.
+ *
+ * ```ts
+ * // syncore/functions/tasks.ts
+ * import { mutation } from "syncorejs";
+ * import { s } from "syncorejs";
+ * import type { MutationCtx } from "../_generated/server";
+ *
+ * export const create = mutation({
+ *   args: { title: s.string() },
+ *   returns: s.id("tasks"),
+ *   handler: async (ctx: MutationCtx, { title }) => {
+ *     return ctx.db.insert("tasks", {
+ *       title,
+ *       status: "todo",
+ *       projectId: null,
+ *     });
+ *   },
+ * });
+ * ```
+ *
+ * @param config - The {@link FunctionConfig} describing the args schema,
+ *   optional return-value schema, and handler function.
  */
-declare function mutation<TContext = unknown, TValidator extends Validator<unknown> = Validator<unknown>, TResult = unknown>(config: FunctionConfig<TContext, Infer<TValidator>, TResult> & {
+declare function mutation<TContext = unknown, TValidator extends Validator<unknown, unknown, string> = Validator<unknown, unknown, string>, TResult = unknown>(config: FunctionConfig<TContext, Infer<TValidator>, TResult> & {
   args: TValidator;
 }): SyncoreFunctionDefinition<"mutation", TContext, Infer<TValidator>, TResult>;
 declare function mutation<TContext = unknown, TArgsShape extends ValidatorMap = ValidatorMap, TResult = unknown>(config: FunctionConfig<TContext, InferArgs<TArgsShape>, TResult> & {
@@ -63,34 +263,134 @@ declare function mutation<TContext = unknown, TArgsShape extends ValidatorMap =
 /**
  * Define a Syncore action.
  *
- * Actions can run arbitrary JavaScript and may call other Syncore functions.
+ * Actions are the escape hatch for work that goes beyond reading and writing
+ * the local database. They run **outside** of any transaction, which means
+ * they can:
+ *
+ * - Call external APIs (HTTP, WebSocket, etc.)
+ * - Perform CPU-intensive or long-running work
+ * - Invoke other Syncore functions via `ctx.runMutation` / `ctx.runQuery`
+ * - Schedule deferred jobs via `ctx.scheduler`
+ *
+ * Because actions are non-transactional, database writes must be delegated to
+ * a mutation. This keeps write atomicity in mutations while actions handle
+ * side effects.
+ *
+ * ```ts
+ * // syncore/functions/ai.ts
+ * import { action } from "syncorejs";
+ * import { s } from "syncorejs";
+ * import type { ActionCtx } from "../_generated/server";
+ * import { api } from "../_generated/api";
+ *
+ * export const summarise = action({
+ *   args: { taskId: s.id("tasks") },
+ *   handler: async (ctx: ActionCtx, { taskId }) => {
+ *     const task = await ctx.runQuery(api.tasks.get, { id: taskId });
+ *     const summary = await fetchSummaryFromApi(task.title);
+ *     await ctx.runMutation(api.tasks.setSummary, { taskId, summary });
+ *   },
+ * });
+ * ```
+ *
+ * @param config - The {@link FunctionConfig} describing the args schema,
+ *   optional return-value schema, and handler function.
  */
-declare function action<TContext = unknown, TValidator extends Validator<unknown> = Validator<unknown>, TResult = unknown>(config: FunctionConfig<TContext, Infer<TValidator>, TResult> & {
+declare function action<TContext = unknown, TValidator extends Validator<unknown, unknown, string> = Validator<unknown, unknown, string>, TResult = unknown>(config: FunctionConfig<TContext, Infer<TValidator>, TResult> & {
   args: TValidator;
 }): SyncoreFunctionDefinition<"action", TContext, Infer<TValidator>, TResult>;
 declare function action<TContext = unknown, TArgsShape extends ValidatorMap = ValidatorMap, TResult = unknown>(config: FunctionConfig<TContext, InferArgs<TArgsShape>, TResult> & {
   args: TArgsShape;
 }): SyncoreFunctionDefinition<"action", TContext, InferArgs<TArgsShape>, TResult>;
+/**
+ * Runs a recurring job repeatedly at a fixed time interval.
+ *
+ * At least one of `seconds`, `minutes`, or `hours` must be provided; multiple
+ * fields are additive (e.g. `{ hours: 1, minutes: 30 }` fires every 90 minutes).
+ *
+ * ```ts
+ * crons.interval("refresh-cache", { minutes: 15 }, api.cache.refresh);
+ * ```
+ */
 interface RecurringIntervalSchedule {
   type: "interval";
+  /** Number of seconds to add to the interval. */
   seconds?: number;
+  /** Number of minutes to add to the interval. */
   minutes?: number;
+  /** Number of hours to add to the interval. */
   hours?: number;
 }
+/**
+ * Runs a recurring job once a day at a specific wall-clock time.
+ *
+ * ```ts
+ * crons.daily("nightly-report", { hour: 2, minute: 0 }, api.reports.generate);
+ * ```
+ */
 interface RecurringDailySchedule {
   type: "daily";
+  /** Hour of day to run (0–23, in UTC unless `timezone` is provided). */
   hour: number;
+  /** Minute of hour to run (0–59). */
   minute: number;
+  /**
+   * IANA timezone name (e.g. `"America/New_York"`). Defaults to UTC when
+   * omitted.
+   */
   timezone?: string;
 }
+/**
+ * Runs a recurring job once a week on a specific day and time.
+ *
+ * ```ts
+ * crons.weekly(
+ *   "weekly-digest",
+ *   { dayOfWeek: "monday", hour: 9, minute: 0, timezone: "Europe/London" },
+ *   api.email.weeklyDigest
+ * );
+ * ```
+ */
 interface RecurringWeeklySchedule {
   type: "weekly";
+  /** Day of the week on which to fire. */
   dayOfWeek: "sunday" | "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday";
+  /** Hour of day to run (0–23, in UTC unless `timezone` is provided). */
   hour: number;
+  /** Minute of hour to run (0–59). */
   minute: number;
+  /**
+   * IANA timezone name (e.g. `"America/New_York"`). Defaults to UTC when
+   * omitted.
+   */
   timezone?: string;
 }
+/**
+ * Union of all supported recurring-schedule shapes.
+ *
+ * Pass this (or one of its members) to {@link RecurringJobDefinition.schedule}
+ * or to the fluent helpers on {@link CronJobs}.
+ */
 type RecurringSchedule = RecurringIntervalSchedule | RecurringDailySchedule | RecurringWeeklySchedule;
+/**
+ * Determines how the scheduler reacts when a job run is missed (e.g. because
+ * the runtime was offline when the job was supposed to fire).
+ *
+ * - `"catch_up"` — Run the job once for every missed execution window. Use for
+ *   jobs where every run matters (e.g. per-minute metrics collection).
+ * - `"skip"` — Skip all missed runs and resume on the next scheduled tick.
+ *   Safe default when running the job twice in quick succession would be
+ *   harmful.
+ * - `"run_once_if_missed"` — If any runs were missed, execute the job exactly
+ *   once to “catch up”, then continue on the normal schedule.
+ * - `"windowed"` — Catch up, but only within a specific time window. Missed
+ *   runs older than `windowMs` milliseconds are discarded.
+ *
+ * @example
+ * ```ts
+ * const policy: MisfirePolicy = { type: "windowed", windowMs: 5 * 60_000 };
+ * ```
+ */
 type MisfirePolicy = {
   type: "catch_up";
 } | {
@@ -101,21 +401,103 @@ type MisfirePolicy = {
   type: "windowed";
   windowMs: number;
 };
+/**
+ * A single entry in the recurring-job registry.
+ *
+ * You can construct these manually and pass them to `scheduler.recurringJobs`,
+ * but the fluent {@link CronJobs} builder is usually more readable.
+ */
 interface RecurringJobDefinition {
+  /** Unique name used to identify this job in the scheduler and devtools UI. */
   name: string;
+  /** When and how often this job should run. */
   schedule: RecurringSchedule;
+  /** The function to invoke. Must be a mutation or action reference. */
   function: FunctionReference<"mutation" | "action">;
+  /** Arguments forwarded to the function on every invocation. */
   args: Record<string, unknown>;
+  /** How to handle missed executions. */
   misfirePolicy: MisfirePolicy;
 }
+/**
+ * Fluent builder for declaring the recurring (cron) jobs of a Syncore app.
+ *
+ * Instantiate with {@link cronJobs} and chain calls to `.interval()`, `.daily()`,
+ * or `.weekly()`. Pass the resulting instance's `.jobs` array to
+ * `scheduler.recurringJobs` in your runtime options.
+ *
+ * ```ts
+ * // syncore/crons.ts
+ * import { cronJobs } from "syncorejs";
+ * import { api } from "./_generated/api";
+ *
+ * const crons = cronJobs();
+ *
+ * crons.interval("refresh-feed",  { minutes: 10 }, api.feed.refresh);
+ * crons.daily("send-digest",       { hour: 8, minute: 0 }, api.email.digest);
+ * crons.weekly("weekly-cleanup",   { dayOfWeek: "sunday", hour: 3, minute: 0 }, api.db.vacuum);
+ *
+ * export default crons;
+ * ```
+ *
+ * Then in your runtime setup:
+ * ```ts
+ * createNodeSyncoreRuntime({
+ *   ...,
+ *   scheduler: { recurringJobs: crons.jobs },
+ * });
+ * ```
+ */
 declare class CronJobs {
   readonly jobs: RecurringJobDefinition[];
+  /**
+   * Register a job that fires repeatedly at a fixed time interval.
+   *
+   * @param name           - Unique identifier for this job.
+   * @param schedule       - Interval fields (`seconds`, `minutes`, `hours`).
+   * @param functionReference - Mutation or action to invoke.
+   * @param args           - Arguments forwarded on every invocation.
+   * @param misfirePolicy  - How to handle runs missed while the runtime was
+   *   offline. Defaults to `{ type: "catch_up" }`.
+   */
   interval(name: string, schedule: Omit<RecurringIntervalSchedule, "type">, functionReference: FunctionReference<"mutation" | "action">, args?: Record<string, unknown>, misfirePolicy?: MisfirePolicy): this;
+  /**
+   * Register a job that fires once a day at a given wall-clock time.
+   *
+   * @param name           - Unique identifier for this job.
+   * @param schedule       - `hour` (0–23), `minute` (0–59), optional `timezone`.
+   * @param functionReference - Mutation or action to invoke.
+   * @param args           - Arguments forwarded on every invocation.
+   * @param misfirePolicy  - How to handle runs missed while the runtime was
+   *   offline. Defaults to `{ type: "catch_up" }`.
+   */
   daily(name: string, schedule: Omit<RecurringDailySchedule, "type">, functionReference: FunctionReference<"mutation" | "action">, args?: Record<string, unknown>, misfirePolicy?: MisfirePolicy): this;
+  /**
+   * Register a job that fires once a week on a given day and time.
+   *
+   * @param name           - Unique identifier for this job.
+   * @param schedule       - `dayOfWeek`, `hour` (0–23), `minute` (0–59),
+   *   optional `timezone`.
+   * @param functionReference - Mutation or action to invoke.
+   * @param args           - Arguments forwarded on every invocation.
+   * @param misfirePolicy  - How to handle runs missed while the runtime was
+   *   offline. Defaults to `{ type: "catch_up" }`.
+   */
   weekly(name: string, schedule: Omit<RecurringWeeklySchedule, "type">, functionReference: FunctionReference<"mutation" | "action">, args?: Record<string, unknown>, misfirePolicy?: MisfirePolicy): this;
 }
 /**
- * Create a recurring job registry for Syncore scheduler definitions.
+ * Create a new {@link CronJobs} builder for declaring recurring Syncore jobs.
+ *
+ * @example
+ * ```ts
+ * // syncore/crons.ts
+ * import { cronJobs } from "syncorejs";
+ * import { api } from "./_generated/api";
+ *
+ * const crons = cronJobs();
+ * crons.interval("sync", { minutes: 5 }, api.sync.run);
+ * export default crons;
+ * ```
  */
 declare function cronJobs(): CronJobs;
 //#endregion

package/dist/_vendor/core/runtime/functions.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"functions.d.mts","names":[],"sources":["../../src/runtime/functions.ts"],"mappings":"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"}
+{"version":3,"file":"functions.d.mts","names":[],"sources":["../../src/runtime/functions.ts"],"mappings":"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"}

package/dist/_vendor/core/runtime/functions.mjs

@@ -1,9 +1,9 @@
-import { ensureObjectValidator } from "../../schema/index.js";
+import { ensureObjectValidator, isValidator } from "../../schema/index.js";
 //#region src/runtime/functions.ts
 function createFunctionDefinition(kind, config) {
 	return {
 		kind,
-		argsValidator: ensureObjectValidator(config.args),
+		argsValidator: isValidator(config.args) ? config.args : ensureObjectValidator(config.args),
 		...config.returns ? { returnsValidator: config.returns } : {},
 		handler: config.handler
 	};
@@ -17,8 +17,47 @@ function mutation(config) {
 function action(config) {
 	return createFunctionDefinition("action", config);
 }
+/**
+* Fluent builder for declaring the recurring (cron) jobs of a Syncore app.
+*
+* Instantiate with {@link cronJobs} and chain calls to `.interval()`, `.daily()`,
+* or `.weekly()`. Pass the resulting instance's `.jobs` array to
+* `scheduler.recurringJobs` in your runtime options.
+*
+* ```ts
+* // syncore/crons.ts
+* import { cronJobs } from "syncorejs";
+* import { api } from "./_generated/api";
+*
+* const crons = cronJobs();
+*
+* crons.interval("refresh-feed",  { minutes: 10 }, api.feed.refresh);
+* crons.daily("send-digest",       { hour: 8, minute: 0 }, api.email.digest);
+* crons.weekly("weekly-cleanup",   { dayOfWeek: "sunday", hour: 3, minute: 0 }, api.db.vacuum);
+*
+* export default crons;
+* ```
+*
+* Then in your runtime setup:
+* ```ts
+* createNodeSyncoreRuntime({
+*   ...,
+*   scheduler: { recurringJobs: crons.jobs },
+* });
+* ```
+*/
 var CronJobs = class {
 	jobs = [];
+	/**
+	* Register a job that fires repeatedly at a fixed time interval.
+	*
+	* @param name           - Unique identifier for this job.
+	* @param schedule       - Interval fields (`seconds`, `minutes`, `hours`).
+	* @param functionReference - Mutation or action to invoke.
+	* @param args           - Arguments forwarded on every invocation.
+	* @param misfirePolicy  - How to handle runs missed while the runtime was
+	*   offline. Defaults to `{ type: "catch_up" }`.
+	*/
 	interval(name, schedule, functionReference, args = {}, misfirePolicy = { type: "catch_up" }) {
 		this.jobs.push({
 			name,
@@ -32,6 +71,16 @@ var CronJobs = class {
 		});
 		return this;
 	}
+	/**
+	* Register a job that fires once a day at a given wall-clock time.
+	*
+	* @param name           - Unique identifier for this job.
+	* @param schedule       - `hour` (0–23), `minute` (0–59), optional `timezone`.
+	* @param functionReference - Mutation or action to invoke.
+	* @param args           - Arguments forwarded on every invocation.
+	* @param misfirePolicy  - How to handle runs missed while the runtime was
+	*   offline. Defaults to `{ type: "catch_up" }`.
+	*/
 	daily(name, schedule, functionReference, args = {}, misfirePolicy = { type: "catch_up" }) {
 		this.jobs.push({
 			name,
@@ -45,6 +94,17 @@ var CronJobs = class {
 		});
 		return this;
 	}
+	/**
+	* Register a job that fires once a week on a given day and time.
+	*
+	* @param name           - Unique identifier for this job.
+	* @param schedule       - `dayOfWeek`, `hour` (0–23), `minute` (0–59),
+	*   optional `timezone`.
+	* @param functionReference - Mutation or action to invoke.
+	* @param args           - Arguments forwarded on every invocation.
+	* @param misfirePolicy  - How to handle runs missed while the runtime was
+	*   offline. Defaults to `{ type: "catch_up" }`.
+	*/
 	weekly(name, schedule, functionReference, args = {}, misfirePolicy = { type: "catch_up" }) {
 		this.jobs.push({
 			name,
@@ -60,7 +120,18 @@ var CronJobs = class {
 	}
 };
 /**
-* Create a recurring job registry for Syncore scheduler definitions.
+* Create a new {@link CronJobs} builder for declaring recurring Syncore jobs.
+*
+* @example
+* ```ts
+* // syncore/crons.ts
+* import { cronJobs } from "syncorejs";
+* import { api } from "./_generated/api";
+*
+* const crons = cronJobs();
+* crons.interval("sync", { minutes: 5 }, api.sync.run);
+* export default crons;
+* ```
 */
 function cronJobs() {
 	return new CronJobs();