@stravigor/core 0.1.0

package/src/notification/types.ts

@@ -0,0 +1,122 @@
+/** A recipient that can receive notifications. */
+export interface Notifiable {
+  /** Unique identifier for the notifiable entity. */
+  notifiableId(): string | number
+  /** Type discriminator (e.g., 'user', 'organization'). */
+  notifiableType(): string
+  /** Email address for the email channel. Returns null to skip email. */
+  routeNotificationForEmail?(): string | null
+  /** Webhook URL for the webhook channel. Returns null to skip. */
+  routeNotificationForWebhook?(): string | null
+  /** Discord webhook URL. Returns null to skip. */
+  routeNotificationForDiscord?(): string | null
+}
+
+// -- Channel envelopes --------------------------------------------------------
+
+/** Envelope produced by a notification for the email channel. */
+export interface MailEnvelope {
+  subject: string
+  template?: string
+  templateData?: Record<string, unknown>
+  html?: string
+  text?: string
+  from?: string
+  cc?: string | string[]
+  bcc?: string | string[]
+  replyTo?: string
+}
+
+/** Envelope produced by a notification for the database (in-app) channel. */
+export interface DatabaseEnvelope {
+  /** Notification type / category (e.g., 'task.assigned', 'invoice.paid'). */
+  type: string
+  /** Structured data stored as JSONB. */
+  data: Record<string, unknown>
+}
+
+/** Envelope produced by a notification for the webhook channel. */
+export interface WebhookEnvelope {
+  /** JSON payload to POST. */
+  payload: Record<string, unknown>
+  /** Optional custom headers. */
+  headers?: Record<string, string>
+  /** Override the webhook URL from notifiable routing. */
+  url?: string
+}
+
+/** Envelope produced by a notification for the Discord channel. */
+export interface DiscordEnvelope {
+  /** Plain text content. */
+  content?: string
+  /** Discord embed objects. */
+  embeds?: DiscordEmbed[]
+  /** Override the webhook URL from notifiable routing. */
+  url?: string
+}
+
+export interface DiscordEmbed {
+  title?: string
+  description?: string
+  url?: string
+  color?: number
+  fields?: { name: string; value: string; inline?: boolean }[]
+  footer?: { text: string }
+  timestamp?: string
+}
+
+// -- Channel interface --------------------------------------------------------
+
+/** Serializable envelope bundle built by BaseNotification. */
+export interface NotificationPayload {
+  notificationClass: string
+  channels: string[]
+  mail?: MailEnvelope
+  database?: DatabaseEnvelope
+  webhook?: WebhookEnvelope
+  discord?: DiscordEnvelope
+}
+
+/**
+ * Pluggable notification channel backend.
+ * Implement this interface for custom channels.
+ */
+export interface NotificationChannel {
+  readonly name: string
+  send(notifiable: Notifiable, payload: NotificationPayload): Promise<void>
+}
+
+// -- Database records ---------------------------------------------------------
+
+/** A stored in-app notification row. */
+export interface NotificationRecord {
+  id: string
+  notifiableType: string
+  notifiableId: string
+  type: string
+  data: Record<string, unknown>
+  readAt: Date | null
+  createdAt: Date
+}
+
+// -- Configuration ------------------------------------------------------------
+
+export interface NotificationConfig {
+  /** Default channels when a notification does not specify via(). */
+  channels: string[]
+  /** Queue name for async notifications. */
+  queue: string
+  /** Named webhook endpoints. */
+  webhooks: Record<string, { url: string; headers?: Record<string, string> }>
+  /** Named Discord webhook URLs. */
+  discord: Record<string, string>
+}
+
+// -- Event binding ------------------------------------------------------------
+
+export interface EventNotificationBinding {
+  /** Factory that creates the notification from the event payload. */
+  create: (payload: any) => import('./base_notification.ts').BaseNotification
+  /** Resolves which notifiable(s) should receive this notification. */
+  recipients: (payload: any) => Notifiable | Notifiable[] | Promise<Notifiable | Notifiable[]>
+}

package/src/orm/base_model.ts

@@ -0,0 +1,351 @@
+import { DateTime } from 'luxon'
+import { toSnakeCase, toCamelCase } from '../helpers/strings.ts'
+import { inject } from '../core/inject.ts'
+import { getPrimaryKey, getReferences, getReferenceMeta, getAssociates } from './decorators.ts'
+import type { ReferenceMetadata, AssociateMetadata } from './decorators.ts'
+import Database from '../database/database.ts'
+import { ConfigurationError, ModelNotFoundError } from '../exceptions/errors.ts'
+
+type ModelStatic<T extends BaseModel> = (new (...args: any[]) => T) & typeof BaseModel
+
+@inject
+export default class BaseModel {
+  private static _db: Database
+
+  /** Whether this model supports soft deletes. Override in subclass. */
+  static softDeletes: boolean = false
+
+  constructor(db?: Database) {
+    if (db) BaseModel._db = db
+  }
+
+  /** The underlying database connection. */
+  static get db(): Database {
+    if (!BaseModel._db) {
+      throw new ConfigurationError('Database not configured. Resolve BaseModel through the container first.')
+    }
+    return BaseModel._db
+  }
+
+  /** Derive table name from class name: User → user, OrderItem → order_item */
+  static get tableName(): string {
+    return toSnakeCase(this.name)
+  }
+
+  /** The primary key column name in snake_case (from @primary metadata). */
+  static get primaryKeyColumn(): string {
+    return toSnakeCase(getPrimaryKey(this))
+  }
+
+  /** The primary key property name in camelCase (from @primary metadata). */
+  static get primaryKeyProperty(): string {
+    return getPrimaryKey(this)
+  }
+
+  /** Whether this record was loaded from (or saved to) the database. */
+  _exists: boolean = false
+
+  // ---------------------------------------------------------------------------
+  // Static CRUD
+  // ---------------------------------------------------------------------------
+
+  /** Find a record by primary key. Returns null if not found or soft-deleted. */
+  static async find<T extends BaseModel>(
+    this: ModelStatic<T>,
+    id: number | string | bigint
+  ): Promise<T | null> {
+    const db = BaseModel.db
+    const table = this.tableName
+    const pkCol = this.primaryKeyColumn
+    const softClause = this.softDeletes ? ' AND "deleted_at" IS NULL' : ''
+    const rows = await db.sql.unsafe(
+      `SELECT * FROM "${table}" WHERE "${pkCol}" = $1${softClause} LIMIT 1`,
+      [id]
+    )
+    if (rows.length === 0) return null
+    return this.hydrate<T>(rows[0] as Record<string, unknown>)
+  }
+
+  /** Find a record by primary key or throw. */
+  static async findOrFail<T extends BaseModel>(
+    this: ModelStatic<T>,
+    id: number | string | bigint
+  ): Promise<T> {
+    const result = (await (this as any).find(id)) as T | null
+    if (!result) {
+      throw new ModelNotFoundError(this.name, id)
+    }
+    return result
+  }
+
+  /** Retrieve all records (excluding soft-deleted). */
+  static async all<T extends BaseModel>(this: ModelStatic<T>): Promise<T[]> {
+    const db = BaseModel.db
+    const table = this.tableName
+    const softClause = this.softDeletes ? ' WHERE "deleted_at" IS NULL' : ''
+    const rows = await db.sql.unsafe(`SELECT * FROM "${table}"${softClause}`)
+    return rows.map((row: Record<string, unknown>) => this.hydrate<T>(row))
+  }
+
+  /** Create a new record, assign attributes, save, and return it. */
+  static async create<T extends BaseModel>(
+    this: ModelStatic<T>,
+    attrs: Record<string, unknown>
+  ): Promise<T> {
+    const instance = new this()
+    instance.merge(attrs)
+    await instance.save()
+    return instance
+  }
+
+  // ---------------------------------------------------------------------------
+  // Instance helpers
+  // ---------------------------------------------------------------------------
+
+  /** Assign properties from a plain object onto this model instance. */
+  merge(data: Record<string, unknown>): this {
+    for (const [key, value] of Object.entries(data)) {
+      ;(this as any)[key] = value
+    }
+    return this
+  }
+
+  // ---------------------------------------------------------------------------
+  // Instance CRUD
+  // ---------------------------------------------------------------------------
+
+  /** INSERT or UPDATE depending on whether the record exists. */
+  async save(): Promise<this> {
+    const ctor = this.constructor as typeof BaseModel
+    const db = BaseModel.db
+    const table = ctor.tableName
+
+    if (this._exists) {
+      return this.performUpdate(db, table)
+    } else {
+      return this.performInsert(db, table)
+    }
+  }
+
+  /** Soft-delete (if model supports it) or hard-delete. */
+  async delete(): Promise<void> {
+    const ctor = this.constructor as typeof BaseModel
+    const db = BaseModel.db
+    const table = ctor.tableName
+    const pkCol = ctor.primaryKeyColumn
+    const pkProp = ctor.primaryKeyProperty
+    const pkValue = (this as any)[pkProp]
+
+    if (ctor.softDeletes && (this as any).deletedAt === null) {
+      const now = DateTime.now()
+      ;(this as any).deletedAt = now
+      await db.sql.unsafe(`UPDATE "${table}" SET "deleted_at" = $1 WHERE "${pkCol}" = $2`, [
+        now.toJSDate(),
+        pkValue,
+      ])
+    } else {
+      await db.sql.unsafe(`DELETE FROM "${table}" WHERE "${pkCol}" = $1`, [pkValue])
+      this._exists = false
+    }
+  }
+
+  /** Always hard-delete, regardless of soft-delete support. */
+  async forceDelete(): Promise<void> {
+    const db = BaseModel.db
+    const ctor = this.constructor as typeof BaseModel
+    const table = ctor.tableName
+    const pkCol = ctor.primaryKeyColumn
+    const pkProp = ctor.primaryKeyProperty
+    const pkValue = (this as any)[pkProp]
+    await db.sql.unsafe(`DELETE FROM "${table}" WHERE "${pkCol}" = $1`, [pkValue])
+    this._exists = false
+  }
+
+  // ---------------------------------------------------------------------------
+  // Relationship loading
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Eagerly load one or more relationships by name.
+   *
+   * Supports both `@reference` (belongs-to) and `@associate` (many-to-many)
+   * relationships. Returns `this` for chaining.
+   *
+   * @example
+   * const team = await Team.find(1)
+   * await team.load('members')          // many-to-many
+   * await user.load('profile', 'teams') // multiple relations
+   */
+  async load(...relations: string[]): Promise<this> {
+    const ctor = this.constructor as typeof BaseModel
+    const refMetas = getReferenceMeta(ctor)
+    const assocMetas = getAssociates(ctor)
+
+    for (const relation of relations) {
+      const refMeta = refMetas.find(r => r.property === relation)
+      if (refMeta) {
+        await this.loadReference(refMeta)
+        continue
+      }
+
+      const assocMeta = assocMetas.find(a => a.property === relation)
+      if (assocMeta) {
+        await this.loadAssociation(assocMeta)
+        continue
+      }
+
+      throw new Error(`Unknown relation "${relation}" on ${ctor.name}`)
+    }
+
+    return this
+  }
+
+  private async loadReference(meta: ReferenceMetadata): Promise<void> {
+    const db = BaseModel.db
+    const fkValue = (this as any)[meta.foreignKey]
+
+    if (fkValue === null || fkValue === undefined) {
+      ;(this as any)[meta.property] = null
+      return
+    }
+
+    const targetTable = toSnakeCase(meta.model)
+    const targetPKCol = toSnakeCase(meta.targetPK)
+    const rows = await db.sql.unsafe(
+      `SELECT * FROM "${targetTable}" WHERE "${targetPKCol}" = $1 LIMIT 1`,
+      [fkValue]
+    )
+
+    ;(this as any)[meta.property] =
+      rows.length > 0 ? hydrateRow(rows[0] as Record<string, unknown>) : null
+  }
+
+  private async loadAssociation(meta: AssociateMetadata): Promise<void> {
+    const db = BaseModel.db
+    const ctor = this.constructor as typeof BaseModel
+    const pkValue = (this as any)[ctor.primaryKeyProperty]
+
+    const targetTable = toSnakeCase(meta.model)
+    const rows = await db.sql.unsafe(
+      `SELECT t.* FROM "${targetTable}" t ` +
+        `INNER JOIN "${meta.through}" p ON p."${meta.otherKey}" = t."${toSnakeCase(meta.targetPK)}" ` +
+        `WHERE p."${meta.foreignKey}" = $1`,
+      [pkValue]
+    )
+
+    ;(this as any)[meta.property] = (rows as Record<string, unknown>[]).map(row => hydrateRow(row))
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+
+  private async performInsert(db: Database, table: string): Promise<this> {
+    const data = this.dehydrate()
+    const columns = Object.keys(data)
+    const values = Object.values(data)
+
+    let sql: string
+    if (columns.length === 0) {
+      sql = `INSERT INTO "${table}" DEFAULT VALUES RETURNING *`
+    } else {
+      const colNames = columns.map(c => `"${c}"`).join(', ')
+      const placeholders = columns.map((_, i) => `$${i + 1}`).join(', ')
+      sql = `INSERT INTO "${table}" (${colNames}) VALUES (${placeholders}) RETURNING *`
+    }
+
+    const rows = await db.sql.unsafe(sql, values)
+
+    if (rows.length > 0) {
+      this.hydrateFrom(rows[0] as Record<string, unknown>)
+    }
+
+    this._exists = true
+    return this
+  }
+
+  private async performUpdate(db: Database, table: string): Promise<this> {
+    if ('updatedAt' in this) (this as any).updatedAt = DateTime.now()
+
+    const ctor = this.constructor as typeof BaseModel
+    const pkCol = ctor.primaryKeyColumn
+
+    const data = this.dehydrate()
+    const pkValue = data[pkCol]
+    delete data[pkCol]
+
+    const columns = Object.keys(data)
+    const values = Object.values(data)
+    const setClauses = columns.map((col, i) => `"${col}" = $${i + 1}`).join(', ')
+    values.push(pkValue)
+
+    await db.sql.unsafe(
+      `UPDATE "${table}" SET ${setClauses} WHERE "${pkCol}" = $${values.length}`,
+      values
+    )
+
+    return this
+  }
+
+  /**
+   * Convert a DB row to a model instance.
+   * snake_case columns → camelCase properties. Date → DateTime.
+   */
+  /** @internal Used by QueryBuilder to create model instances from DB rows. */
+  static hydrate<T extends BaseModel>(this: new () => T, row: Record<string, unknown>): T {
+    const instance = new this()
+    instance.hydrateFrom(row)
+    instance._exists = true
+    return instance
+  }
+
+  /** Populate this instance's properties from a DB row. */
+  private hydrateFrom(row: Record<string, unknown>): void {
+    for (const [column, value] of Object.entries(row)) {
+      const prop = toCamelCase(column)
+      if (value instanceof Date) {
+        ;(this as any)[prop] = DateTime.fromJSDate(value)
+      } else {
+        ;(this as any)[prop] = value
+      }
+    }
+  }
+
+  /**
+   * Convert model properties to DB columns.
+   * Skips _-prefixed props and @reference-decorated properties.
+   */
+  private dehydrate(): Record<string, unknown> {
+    const ctor = this.constructor as typeof BaseModel
+    const refProps = new Set(getReferences(ctor))
+    const assocProps = new Set(getAssociates(ctor).map(a => a.property))
+    const data: Record<string, unknown> = {}
+
+    for (const key of Object.keys(this)) {
+      if (key.startsWith('_')) continue
+      if (refProps.has(key)) continue
+      if (assocProps.has(key)) continue
+
+      const value = (this as any)[key]
+      const column = toSnakeCase(key)
+
+      if (value instanceof DateTime) {
+        data[column] = value.toJSDate()
+      } else {
+        data[column] = value
+      }
+    }
+
+    return data
+  }
+}
+
+/** Convert a raw DB row to a plain object with camelCase keys and DateTime hydration. */
+function hydrateRow(row: Record<string, unknown>): Record<string, unknown> {
+  const obj: Record<string, unknown> = {}
+  for (const [column, value] of Object.entries(row)) {
+    const prop = toCamelCase(column)
+    obj[prop] = value instanceof Date ? DateTime.fromJSDate(value) : value
+  }
+  return obj
+}

package/src/orm/decorators.ts

@@ -0,0 +1,127 @@
+import 'reflect-metadata'
+
+const PRIMARY_KEY = Symbol('orm:primary')
+const REFERENCE_KEY = Symbol('orm:references')
+const REFERENCE_META_KEY = Symbol('orm:reference_meta')
+const ASSOCIATE_KEY = Symbol('orm:associates')
+
+// ---------------------------------------------------------------------------
+// @primary
+// ---------------------------------------------------------------------------
+
+/**
+ * Property decorator that marks a field as the primary key.
+ * BaseModel reads this metadata to build queries with the correct PK column.
+ */
+export function primary(target: any, propertyKey: string) {
+  Reflect.defineMetadata(PRIMARY_KEY, propertyKey, target.constructor)
+}
+
+/** Get the primary key property name (camelCase) for a model class. Defaults to 'id'. */
+export function getPrimaryKey(target: Function): string {
+  return Reflect.getMetadata(PRIMARY_KEY, target) ?? 'id'
+}
+
+// ---------------------------------------------------------------------------
+// @reference
+// ---------------------------------------------------------------------------
+
+export interface ReferenceOptions {
+  model: string
+  foreignKey: string
+  targetPK: string
+}
+
+export interface ReferenceMetadata extends ReferenceOptions {
+  property: string
+}
+
+/**
+ * Property decorator that marks a field as a reference object.
+ * Reference properties are excluded from database persistence (dehydrate).
+ *
+ * Can be used as a bare decorator or with options for load() support.
+ *
+ * @example
+ * // Bare (backward-compatible):
+ * @reference
+ * declare widget: Widget
+ *
+ * // With options (supports load()):
+ * @reference({ model: 'User', foreignKey: 'userId', targetPK: 'id' })
+ * declare user: User
+ */
+export function reference(targetOrOptions: any, propertyKey?: string): any {
+  if (propertyKey !== undefined) {
+    // Bare decorator: @reference
+    addReferenceProperty(targetOrOptions, propertyKey)
+    return
+  }
+
+  // Factory: @reference({ model, foreignKey, targetPK })
+  const options = targetOrOptions as ReferenceOptions
+  return function (target: any, propertyKey: string) {
+    addReferenceProperty(target, propertyKey)
+
+    const metas: ReferenceMetadata[] = [
+      ...(Reflect.getMetadata(REFERENCE_META_KEY, target.constructor) ?? []),
+    ]
+    metas.push({ property: propertyKey, ...options })
+    Reflect.defineMetadata(REFERENCE_META_KEY, metas, target.constructor)
+  }
+}
+
+function addReferenceProperty(target: any, propertyKey: string): void {
+  const refs: string[] = [...(Reflect.getMetadata(REFERENCE_KEY, target.constructor) ?? [])]
+  refs.push(propertyKey)
+  Reflect.defineMetadata(REFERENCE_KEY, refs, target.constructor)
+}
+
+/** Get the list of reference property names for a model class. */
+export function getReferences(target: Function): string[] {
+  return Reflect.getMetadata(REFERENCE_KEY, target) ?? []
+}
+
+/** Get rich @reference metadata (only present when options were used). */
+export function getReferenceMeta(target: Function): ReferenceMetadata[] {
+  return Reflect.getMetadata(REFERENCE_META_KEY, target) ?? []
+}
+
+// ---------------------------------------------------------------------------
+// @associate
+// ---------------------------------------------------------------------------
+
+export interface AssociateOptions {
+  through: string
+  foreignKey: string
+  otherKey: string
+  model: string
+  targetPK: string
+}
+
+export interface AssociateMetadata extends AssociateOptions {
+  property: string
+}
+
+/**
+ * Property decorator that marks a field as a many-to-many association.
+ * Associates are loaded via pivot table queries and excluded from dehydrate.
+ *
+ * @example
+ * @associate({ through: 'team_user', foreignKey: 'team_id', otherKey: 'user_pid', model: 'User', targetPK: 'pid' })
+ * declare members: User[]
+ */
+export function associate(options: AssociateOptions) {
+  return function (target: any, propertyKey: string) {
+    const assocs: AssociateMetadata[] = [
+      ...(Reflect.getMetadata(ASSOCIATE_KEY, target.constructor) ?? []),
+    ]
+    assocs.push({ property: propertyKey, ...options })
+    Reflect.defineMetadata(ASSOCIATE_KEY, assocs, target.constructor)
+  }
+}
+
+/** Get all @associate metadata for a model class. */
+export function getAssociates(target: Function): AssociateMetadata[] {
+  return Reflect.getMetadata(ASSOCIATE_KEY, target) ?? []
+}

package/src/orm/index.ts

@@ -0,0 +1,4 @@
+export { default as BaseModel } from './base_model.ts'
+export { primary, reference, associate } from './decorators.ts'
+export { default as QueryBuilder, query } from '../database/query_builder.ts'
+export type { PaginationResult, PaginationMeta } from '../database/query_builder.ts'

package/src/policy/authorize.ts

@@ -0,0 +1,44 @@
+import type { Middleware } from '../http/middleware.ts'
+import type { PolicyResult } from './policy_result.ts'
+
+type PolicyReturn = PolicyResult | Promise<PolicyResult>
+
+export function authorize(
+  policy: Record<string, (...args: any[]) => PolicyReturn>,
+  method: string,
+  loadResource?: (ctx: import('../http/context.ts').default) => Promise<unknown>
+): Middleware {
+  return async (ctx, next) => {
+    const user = ctx.get('user')
+    if (!user) {
+      return new Response(JSON.stringify({ error: 'Unauthorized' }), {
+        status: 401,
+        headers: { 'Content-Type': 'application/json' },
+      })
+    }
+
+    let resource: unknown
+    if (loadResource) {
+      resource = await loadResource(ctx)
+      ctx.set('resource', resource)
+    }
+
+    const policyMethod = policy[method]
+    if (!policyMethod) {
+      return new Response(JSON.stringify({ error: 'Forbidden' }), {
+        status: 403,
+        headers: { 'Content-Type': 'application/json' },
+      })
+    }
+
+    const access = await policyMethod(user, resource)
+    if (!access.allowed) {
+      return new Response(JSON.stringify({ error: access.reason }), {
+        status: access.status,
+        headers: { 'Content-Type': 'application/json' },
+      })
+    }
+
+    return next()
+  }
+}

package/src/policy/index.ts

@@ -0,0 +1,3 @@
+export { authorize } from './authorize.ts'
+export { allow, deny } from './policy_result.ts'
+export type { PolicyResult } from './policy_result.ts'

package/src/policy/policy_result.ts

@@ -0,0 +1,13 @@
+export type PolicyResult = {
+  allowed: boolean
+  status: number
+  reason: string
+}
+
+export function allow(): PolicyResult {
+  return { allowed: true, status: 200, reason: '' }
+}
+
+export function deny(status = 403, reason = 'Action forbidden'): PolicyResult {
+  return { allowed: false, status, reason }
+}

package/src/queue/index.ts

@@ -0,0 +1,11 @@
+export { default as Queue } from './queue.ts'
+export { default as Worker } from './worker.ts'
+export type {
+  JobOptions,
+  QueueConfig,
+  JobMeta,
+  JobRecord,
+  FailedJobRecord,
+  JobHandler,
+} from './queue.ts'
+export type { WorkerOptions } from './worker.ts'