@stravigor/core 0.1.0

package/src/scheduler/runner.ts

@@ -0,0 +1,116 @@
+import Scheduler from './scheduler.ts'
+import type { Schedule } from './schedule.ts'
+
+export interface RunnerOptions {
+  /** Timezone for schedule evaluation. @default 'UTC' */
+  timezone?: string
+}
+
+/**
+ * Long-running scheduler loop.
+ *
+ * Aligns to minute boundaries (standard cron behaviour), checks which
+ * tasks are due, and executes them concurrently. Supports graceful
+ * shutdown via SIGINT/SIGTERM and per-task overlap prevention.
+ *
+ * @example
+ * const runner = new SchedulerRunner()
+ * await runner.start() // blocks until runner.stop()
+ */
+export default class SchedulerRunner {
+  private running = false
+  private active = new Set<string>()
+
+  /** Start the scheduler loop. Blocks until stop() is called. */
+  async start(): Promise<void> {
+    this.running = true
+
+    const onSignal = () => this.stop()
+    process.on('SIGINT', onSignal)
+    process.on('SIGTERM', onSignal)
+
+    try {
+      while (this.running) {
+        await this.sleepUntilNextMinute()
+        if (!this.running) break
+
+        const now = new Date()
+        const due = Scheduler.due(now)
+
+        if (due.length > 0) {
+          await this.runAll(due)
+        }
+      }
+
+      // Wait for active tasks to finish before exiting
+      if (this.active.size > 0) {
+        await this.waitForActive()
+      }
+    } finally {
+      process.off('SIGINT', onSignal)
+      process.off('SIGTERM', onSignal)
+    }
+  }
+
+  /** Signal the runner to stop after the current tick completes. */
+  stop(): void {
+    this.running = false
+  }
+
+  /** Number of tasks currently executing. */
+  get activeCount(): number {
+    return this.active.size
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+
+  /** Sleep until the start of the next minute (XX:XX:00.000). */
+  private async sleepUntilNextMinute(): Promise<void> {
+    const now = Date.now()
+    const nextMinute = Math.ceil(now / 60_000) * 60_000
+    const delay = nextMinute - now
+
+    // Minimum 1s, maximum 60s — avoid sleeping 0ms on exact boundaries
+    const ms = Math.max(1_000, Math.min(delay, 60_000))
+    await Bun.sleep(ms)
+  }
+
+  /** Execute all due tasks concurrently. */
+  private async runAll(tasks: Schedule[]): Promise<void> {
+    const promises: Promise<void>[] = []
+
+    for (const task of tasks) {
+      if (task.preventsOverlap && this.active.has(task.name)) {
+        continue
+      }
+
+      promises.push(this.runTask(task))
+    }
+
+    await Promise.allSettled(promises)
+  }
+
+  /** Execute a single task with overlap tracking and error handling. */
+  private async runTask(task: Schedule): Promise<void> {
+    this.active.add(task.name)
+    try {
+      await task.handler()
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      console.error(`[scheduler] Task "${task.name}" failed: ${message}`)
+    } finally {
+      this.active.delete(task.name)
+    }
+  }
+
+  /** Wait for all active tasks to complete (for graceful shutdown). */
+  private async waitForActive(): Promise<void> {
+    const maxWait = 30_000
+    const start = Date.now()
+    while (this.active.size > 0 && Date.now() - start < maxWait) {
+      await Bun.sleep(100)
+    }
+  }
+}

package/src/scheduler/schedule.ts

@@ -0,0 +1,183 @@
+import { parseCron, cronMatches } from './cron.ts'
+import type { CronExpression } from './cron.ts'
+
+export type TaskHandler = () => void | Promise<void>
+
+const DAY_NAMES: Record<string, number> = {
+  sunday: 0, sun: 0,
+  monday: 1, mon: 1,
+  tuesday: 2, tue: 2,
+  wednesday: 3, wed: 3,
+  thursday: 4, thu: 4,
+  friday: 5, fri: 5,
+  saturday: 6, sat: 6,
+}
+
+/**
+ * A scheduled task definition with a fluent configuration API.
+ *
+ * @example
+ * new Schedule('cleanup', handler).dailyAt('02:30').withoutOverlapping()
+ */
+export class Schedule {
+  readonly name: string
+  readonly handler: TaskHandler
+
+  private _cron: CronExpression | null = null
+  private _noOverlap = false
+
+  constructor(name: string, handler: TaskHandler) {
+    this.name = name
+    this.handler = handler
+  }
+
+  // ── Raw cron ──────────────────────────────────────────────────────────────
+
+  /** Set a raw 5-field cron expression. */
+  cron(expression: string): this {
+    this._cron = parseCron(expression)
+    return this
+  }
+
+  // ── Minute-based ──────────────────────────────────────────────────────────
+
+  /** Run every minute. */
+  everyMinute(): this {
+    return this.cron('* * * * *')
+  }
+
+  /** Run every 2 minutes. */
+  everyTwoMinutes(): this {
+    return this.cron('*/2 * * * *')
+  }
+
+  /** Run every 5 minutes. */
+  everyFiveMinutes(): this {
+    return this.cron('*/5 * * * *')
+  }
+
+  /** Run every 10 minutes. */
+  everyTenMinutes(): this {
+    return this.cron('*/10 * * * *')
+  }
+
+  /** Run every 15 minutes. */
+  everyFifteenMinutes(): this {
+    return this.cron('*/15 * * * *')
+  }
+
+  /** Run every 30 minutes. */
+  everyThirtyMinutes(): this {
+    return this.cron('*/30 * * * *')
+  }
+
+  // ── Hourly ────────────────────────────────────────────────────────────────
+
+  /** Run once per hour at minute 0. */
+  hourly(): this {
+    return this.cron('0 * * * *')
+  }
+
+  /** Run once per hour at the given minute. */
+  hourlyAt(minute: number): this {
+    return this.cron(`${minute} * * * *`)
+  }
+
+  // ── Daily ─────────────────────────────────────────────────────────────────
+
+  /** Run once per day at midnight. */
+  daily(): this {
+    return this.cron('0 0 * * *')
+  }
+
+  /** Run once per day at the given time (HH:MM). */
+  dailyAt(time: string): this {
+    const [hour, minute] = parseTime(time)
+    return this.cron(`${minute} ${hour} * * *`)
+  }
+
+  /** Run twice per day at the given hours (minute 0). */
+  twiceDaily(hour1: number, hour2: number): this {
+    return this.cron(`0 ${hour1},${hour2} * * *`)
+  }
+
+  // ── Weekly ────────────────────────────────────────────────────────────────
+
+  /** Run once per week on Sunday at midnight. */
+  weekly(): this {
+    return this.cron('0 0 * * 0')
+  }
+
+  /** Run once per week on the given day and optional time. */
+  weeklyOn(day: string | number, time?: string): this {
+    const dow = typeof day === 'string' ? dayToNumber(day) : day
+    const [hour, minute] = time ? parseTime(time) : [0, 0]
+    return this.cron(`${minute} ${hour} * * ${dow}`)
+  }
+
+  // ── Monthly ───────────────────────────────────────────────────────────────
+
+  /** Run once per month on the 1st at midnight. */
+  monthly(): this {
+    return this.cron('0 0 1 * *')
+  }
+
+  /** Run once per month on the given day and optional time. */
+  monthlyOn(day: number, time?: string): this {
+    const [hour, minute] = time ? parseTime(time) : [0, 0]
+    return this.cron(`${minute} ${hour} ${day} * *`)
+  }
+
+  // ── Options ───────────────────────────────────────────────────────────────
+
+  /** Prevent overlapping runs within this process. */
+  withoutOverlapping(): this {
+    this._noOverlap = true
+    return this
+  }
+
+  // ── Internal ──────────────────────────────────────────────────────────────
+
+  /** Check if this task is due at the given Date (evaluated in UTC). */
+  isDue(now: Date): boolean {
+    if (!this._cron) return false
+    return cronMatches(this._cron, now)
+  }
+
+  /** Whether overlap prevention is enabled. */
+  get preventsOverlap(): boolean {
+    return this._noOverlap
+  }
+
+  /** The parsed cron expression (for testing/debugging). */
+  get expression(): CronExpression | null {
+    return this._cron
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function parseTime(time: string): [number, number] {
+  const parts = time.split(':')
+  if (parts.length !== 2) {
+    throw new Error(`Invalid time format "${time}": expected HH:MM`)
+  }
+  const hour = parseInt(parts[0]!, 10)
+  const minute = parseInt(parts[1]!, 10)
+  if (isNaN(hour) || isNaN(minute) || hour < 0 || hour > 23 || minute < 0 || minute > 59) {
+    throw new Error(`Invalid time "${time}": hour must be 0–23, minute must be 0–59`)
+  }
+  return [hour, minute]
+}
+
+function dayToNumber(day: string): number {
+  const n = DAY_NAMES[day.toLowerCase()]
+  if (n === undefined) {
+    throw new Error(
+      `Invalid day name "${day}": expected one of ${Object.keys(DAY_NAMES).filter((_, i) => i % 2 === 0).join(', ')}`
+    )
+  }
+  return n
+}

package/src/scheduler/scheduler.ts

@@ -0,0 +1,47 @@
+import { Schedule } from './schedule.ts'
+import type { TaskHandler } from './schedule.ts'
+
+/**
+ * Static task registry for periodic jobs.
+ *
+ * No DI, no database — tasks are registered in code and evaluated
+ * in-memory by the {@link SchedulerRunner}.
+ *
+ * @example
+ * Scheduler.task('cleanup:sessions', async () => {
+ *   await db.sql`DELETE FROM "_strav_sessions" WHERE "expires_at" < NOW()`
+ * }).hourly()
+ *
+ * Scheduler.task('reports:daily', () => generateDailyReport()).dailyAt('02:00')
+ */
+export default class Scheduler {
+  private static _tasks: Schedule[] = []
+
+  /**
+   * Register a periodic task. Returns the {@link Schedule} for fluent configuration.
+   *
+   * @example
+   * Scheduler.task('prune-cache', () => cache.flush()).everyFifteenMinutes()
+   */
+  static task(name: string, handler: TaskHandler): Schedule {
+    const schedule = new Schedule(name, handler)
+    Scheduler._tasks.push(schedule)
+    return schedule
+  }
+
+  /** All registered tasks. */
+  static get tasks(): readonly Schedule[] {
+    return Scheduler._tasks
+  }
+
+  /** Return tasks that are due at the given time (defaults to now, UTC). */
+  static due(now?: Date): Schedule[] {
+    const date = now ?? new Date()
+    return Scheduler._tasks.filter(t => t.isDue(date))
+  }
+
+  /** Clear all registered tasks. For testing. */
+  static reset(): void {
+    Scheduler._tasks = []
+  }
+}

package/src/schema/database_representation.ts

@@ -0,0 +1,122 @@
+import type { PostgreSQLType } from './postgres.ts'
+import type { Archetype } from './types.ts'
+
+/**
+ * Represents the full database schema derived from all registered SchemaDefinitions.
+ * Contains all enum types and table definitions in dependency order.
+ */
+export interface DatabaseRepresentation {
+  /** PostgreSQL enum types that must be created before tables. */
+  enums: EnumDefinition[]
+  /** Table definitions in dependency order. */
+  tables: TableDefinition[]
+}
+
+/**
+ * A PostgreSQL CREATE TYPE ... AS ENUM definition.
+ */
+export interface EnumDefinition {
+  /** Enum type name (e.g. 'order_status'). */
+  name: string
+  /** Allowed values. */
+  values: string[]
+}
+
+/**
+ * A PostgreSQL table definition.
+ */
+export interface TableDefinition {
+  /** Table name in snake_case, not pluralized. */
+  name: string
+  /** The archetype this table was derived from (absent when introspected from DB). */
+  archetype?: Archetype
+  /** Ordered list of columns. */
+  columns: ColumnDefinition[]
+  /** Primary key constraint, or null for associations. */
+  primaryKey: PrimaryKeyConstraint | null
+  /** Foreign key constraints. */
+  foreignKeys: ForeignKeyConstraint[]
+  /** Unique constraints (beyond individual column UNIQUE). */
+  uniqueConstraints: UniqueConstraint[]
+  /** Index definitions. */
+  indexes: IndexDefinition[]
+}
+
+/**
+ * A single column in a table.
+ */
+export interface ColumnDefinition {
+  /** Column name in snake_case. */
+  name: string
+  /** PostgreSQL column type. */
+  pgType: PostgreSQLType
+  /** Whether the column is NOT NULL. */
+  notNull: boolean
+  /** Default value (literal or SQL expression). */
+  defaultValue?: DefaultValue
+  /** Whether the column has a UNIQUE constraint. */
+  unique: boolean
+  /** Whether the column is part of the primary key. */
+  primaryKey: boolean
+  /** Whether the column is auto-incrementing (serial). */
+  autoIncrement: boolean
+  /** Whether the column should be indexed. */
+  index: boolean
+  /** Whether the column contains sensitive data (app-level, absent when introspected). */
+  sensitive?: boolean
+  /** Whether this is an array column. */
+  isArray: boolean
+  /** Array dimensions. */
+  arrayDimensions: number
+  /** Max length for varchar/char. */
+  length?: number
+  /** Precision for decimal/numeric. */
+  precision?: number
+  /** Scale for decimal/numeric. */
+  scale?: number
+}
+
+/**
+ * A default value for a column — either a literal value or a SQL expression.
+ */
+export type DefaultValue =
+  | { kind: 'literal'; value: string | number | boolean | null }
+  | { kind: 'expression'; sql: string }
+
+/**
+ * A primary key constraint (single or composite).
+ */
+export interface PrimaryKeyConstraint {
+  columns: string[]
+}
+
+/**
+ * A foreign key constraint.
+ */
+export interface ForeignKeyConstraint {
+  /** Column(s) in this table. */
+  columns: string[]
+  /** Referenced table. */
+  referencedTable: string
+  /** Referenced column(s). */
+  referencedColumns: string[]
+  /** ON DELETE behavior. */
+  onDelete: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION'
+  /** ON UPDATE behavior. */
+  onUpdate: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION'
+}
+
+/**
+ * A unique constraint across one or more columns.
+ */
+export interface UniqueConstraint {
+  columns: string[]
+}
+
+/**
+ * An index definition.
+ */
+export interface IndexDefinition {
+  columns: string[]
+  unique: boolean
+}

package/src/schema/define_association.ts

@@ -0,0 +1,60 @@
+import { Archetype } from './types.ts'
+import type { SchemaDefinition } from './types.ts'
+import type FieldBuilder from './field_builder.ts'
+import defineSchema from './define_schema.ts'
+
+interface AssociationOptions {
+  as?: Record<string, string>
+  fields?: Record<string, FieldBuilder>
+}
+
+/**
+ * Define an association (many-to-many junction) schema between two entities.
+ *
+ * Automatically sets archetype to `'association'`, generates the table name
+ * as `{entityA}_{entityB}`, and records the two associates.
+ *
+ * Only specify additional pivot fields — the FK columns to both entities
+ * are injected automatically by the {@link RepresentationBuilder}.
+ *
+ * @example
+ * // With named properties on each entity model:
+ * export default defineAssociation(['team', 'user'], {
+ *   as: { team: 'members', user: 'teams' },
+ *   fields: {
+ *     role: t.enum(['admin', 'developer', 'tester']),
+ *   },
+ * })
+ *
+ * // Legacy shorthand (fields only, no model properties):
+ * export default defineAssociation(['team', 'user'], {
+ *   role: t.enum(['admin', 'developer', 'tester']),
+ * })
+ */
+export default function defineAssociation(
+  entities: [string, string],
+  options: AssociationOptions | Record<string, FieldBuilder> = {}
+): SchemaDefinition {
+  const [entityA, entityB] = entities
+
+  let fields: Record<string, FieldBuilder>
+  let as: Record<string, string> | undefined
+
+  if (isAssociationOptions(options)) {
+    fields = options.fields ?? {}
+    as = options.as
+  } else {
+    fields = options
+  }
+
+  return defineSchema(`${entityA}_${entityB}`, {
+    archetype: Archetype.Association,
+    associates: [entityA, entityB],
+    as,
+    fields,
+  })
+}
+
+function isAssociationOptions(obj: unknown): obj is AssociationOptions {
+  return typeof obj === 'object' && obj !== null && ('as' in obj || 'fields' in obj)
+}

package/src/schema/define_schema.ts

@@ -0,0 +1,46 @@
+import { Archetype } from './types.ts'
+import type { SchemaInput, SchemaDefinition } from './types.ts'
+import type { FieldDefinition } from './field_definition.ts'
+import type { PostgreSQLCustomType } from './postgres.ts'
+
+/**
+ * Define a data schema for the application.
+ *
+ * Resolves all {@link FieldBuilder} instances into {@link FieldDefinition}s,
+ * assigns proper enum names, and returns a {@link SchemaDefinition}.
+ *
+ * @example
+ * export default defineSchema('user', {
+ *   archetype: Archetype.Entity,
+ *   fields: {
+ *     email: t.varchar().email().unique().required(),
+ *     role:  t.enum(['user', 'admin']).default('user'),
+ *   },
+ * })
+ */
+export default function defineSchema(name: string, input: SchemaInput): SchemaDefinition {
+  const fields: Record<string, FieldDefinition> = {}
+
+  for (const [fieldName, builder] of Object.entries(input.fields)) {
+    const def = builder.toDefinition()
+
+    if (isCustomType(def.pgType) && def.pgType.values?.length) {
+      def.pgType = { ...def.pgType, name: `${name}_${fieldName}` }
+    }
+
+    fields[fieldName] = def
+  }
+
+  return {
+    name,
+    archetype: input.archetype ?? Archetype.Entity,
+    parent: input.parent,
+    associates: input.associates,
+    as: input.as,
+    fields,
+  }
+}
+
+function isCustomType(pgType: unknown): pgType is PostgreSQLCustomType {
+  return typeof pgType === 'object' && pgType !== null && (pgType as any).type === 'custom'
+}