frappebun 0.0.0

package/src/context.ts

@@ -0,0 +1,162 @@
+/**
+ * Per-request context via AsyncLocalStorage.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks"
+
+import type { FrappeDatabase } from "./database/database"
+import type { QueryBuilder } from "./database/query-builder"
+import type { Dict, FilterInput } from "./doctype/types"
+import type { Document } from "./document/document"
+import { ValidationError, type FrappeError } from "./errors"
+import type { PermsNamespace } from "./permissions"
+import type { FrappeResponse } from "./response"
+
+export type { Dict }
+
+export interface SessionContext {
+  user: string
+  sid?: string
+  csrfToken?: string
+}
+
+export interface GetListArgs {
+  filters?: FilterInput
+  fields?: string[]
+  orderBy?: string
+  limit?: number
+  offset?: number
+}
+
+export interface FrappeContext {
+  user: string
+  site: string
+  session: SessionContext
+  context: "request" | "job" | "migrate" | "install" | "test" | "console"
+  env: "development" | "production" | "test"
+  flags: Dict
+  cache: Dict
+  db: FrappeDatabase
+  perms: PermsNamespace
+  response: FrappeResponse
+  request?: Request
+
+  /** Create a QueryBuilder for the given DocType, bound to this context's database. */
+  query(doctype: string): QueryBuilder
+
+  getDoc(doctype: string, name: string): Promise<Document>
+  newDoc(doctype: string, data?: Dict): Document
+  getList(doctype: string, args?: GetListArgs): Promise<Dict[]>
+  getSingle(doctype: string, fieldOrFields?: string | string[]): Promise<unknown>
+  deleteDoc(doctype: string, name: string): Promise<void>
+
+  throw(
+    msg: string,
+    exc?: new (message: string, title?: string) => FrappeError,
+    title?: string,
+  ): never
+}
+
+export const contextStore = new AsyncLocalStorage<FrappeContext>()
+
+export interface CreateContextOptions {
+  user?: string
+  site?: string
+  context?: FrappeContext["context"]
+  env?: FrappeContext["env"]
+  db?: FrappeDatabase
+  sid?: string
+  csrfToken?: string
+  request?: Request
+}
+
+export function createContext(opts: CreateContextOptions): FrappeContext {
+  const user = opts.user ?? "Guest"
+
+  // Lazy require() to avoid circular deps at module load time.
+  // oxlint-disable-next-line typescript/consistent-type-imports
+  const docModule = require("./document/document") as typeof import("./document/document") // eslint-disable-line @typescript-eslint/no-require-imports
+  const { createQueryBuilder } =
+    // oxlint-disable-next-line typescript/consistent-type-imports
+    require("./database/query-builder") as typeof import("./database/query-builder") // eslint-disable-line @typescript-eslint/no-require-imports
+  // oxlint-disable-next-line typescript/consistent-type-imports
+  const { createPermsNamespace } = require("./permissions") as typeof import("./permissions") // eslint-disable-line @typescript-eslint/no-require-imports
+  // oxlint-disable-next-line typescript/consistent-type-imports
+  const { response } = require("./response") as typeof import("./response") // eslint-disable-line @typescript-eslint/no-require-imports
+
+  const ctx: FrappeContext = {
+    user,
+    site: opts.site ?? "",
+    session: { user, sid: opts.sid, csrfToken: opts.csrfToken },
+    context: opts.context ?? "request",
+    env: (opts.env ?? process.env["NODE_ENV"] ?? "development") as FrappeContext["env"],
+    flags: {},
+    cache: {},
+    db: opts.db as FrappeDatabase,
+    response,
+    request: opts.request,
+
+    // Filled in below once ctx is fully constructed
+    perms: undefined as unknown as PermsNamespace,
+
+    query(doctype: string): QueryBuilder {
+      return createQueryBuilder(ctx.db.raw, doctype)
+    },
+
+    getDoc(doctype, name) {
+      return docModule.getDoc(doctype, name, ctx.db, ctx.user)
+    },
+
+    newDoc(doctype, data) {
+      return docModule.newDoc(doctype, data, ctx.db, ctx.user)
+    },
+
+    async getList(doctype, args) {
+      // oxlint-disable-next-line typescript/consistent-type-imports
+      const { getController } = require("./doctype/registry") as typeof import("./doctype/registry") // eslint-disable-line @typescript-eslint/no-require-imports
+      const controller = getController(doctype)
+      const scopeFn = controller?.permissions?.scope
+
+      if (scopeFn) {
+        const scopeQb = scopeFn(ctx.user) as QueryBuilder | null
+        if (scopeQb !== null) {
+          const a = args ?? {}
+          const fields = a.fields ?? ["name"]
+          const orderBy = (a.orderBy ?? "modified DESC") as string
+          const [orderField, rawDir] = orderBy.split(/\s+/, 2)
+          const orderDir = (rawDir ?? "desc").toLowerCase() as "asc" | "desc"
+
+          let qb = scopeQb.select(...fields)
+          if (a.filters) qb = qb.where(a.filters) as QueryBuilder
+          if (orderField) qb = qb.orderBy(orderField, orderDir) as QueryBuilder
+          return qb
+            .limit(a.limit ?? 20)
+            .offset(a.offset ?? 0)
+            .all<Dict>()
+        }
+      }
+
+      return docModule.getList(doctype, args ?? {}, ctx.db)
+    },
+
+    async getSingle(doctype, fieldOrFields) {
+      return docModule.getSingle(doctype, fieldOrFields, ctx.db, ctx.user)
+    },
+
+    deleteDoc(doctype, name) {
+      return docModule.deleteDoc(doctype, name, ctx.db, ctx.user)
+    },
+
+    throw(msg, exc, title) {
+      const ErrorClass = exc ?? ValidationError
+      throw new ErrorClass(msg, title)
+    },
+  }
+
+  // Initialise perms — uses ctx as the per-request cache key
+  ctx.perms = createPermsNamespace(user, ctx.db, ctx as object, (doctype, name) =>
+    ctx.getDoc(doctype, name),
+  )
+
+  return ctx
+}

package/src/core/doctype/migration/migration.ts

@@ -0,0 +1,17 @@
+export default doctype("Migration", {
+  naming: "field:migrationName",
+  module: "Core",
+  fields: {
+    migrationName: field.data({ required: true, unique: true }),
+    app: field.data({ required: true }),
+    phase: field.select(["before", "after"]),
+    executedAt: field.datetime(),
+    status: field.select(["Success", "Failed"]),
+    error: field.longText(),
+  },
+  permissions: [{ role: "System Manager", read: true }],
+  list: {
+    fields: ["migrationName", "app", "phase", "status", "executedAt"],
+    titleField: "migrationName",
+  },
+})

package/src/core/doctype/role/role.ts

@@ -0,0 +1,7 @@
+export default doctype("Role", {
+  naming: "field:roleName",
+  module: "Core",
+  fields: {
+    roleName: field.data({ required: true, unique: true }),
+  },
+})

package/src/core/doctype/session/session.ts

@@ -0,0 +1,16 @@
+export default doctype("Session", {
+  naming: "uuid",
+  module: "Core",
+  fields: {
+    user: field.link("User", { required: true }),
+    sid: field.data({ required: true, unique: true }),
+    device: field.data(),
+    ipAddress: field.data(),
+    userAgent: field.smallText(),
+    expiresAt: field.datetime({ required: true }),
+    lastActive: field.datetime(),
+    status: field.select(["Active", "Expired", "Logged Out"], { default: "Active" }),
+    csrfToken: field.data(),
+  },
+  permissions: [{ role: "System Manager", read: true, write: true, delete: true }],
+})

package/src/core/doctype/user/user.controller.ts

@@ -0,0 +1,11 @@
+export default controller("User", {
+  async validate(doc) {
+    // Email is used as the document name, so it cannot be changed after creation
+    if (!doc.isNew()) {
+      const dbEmail = await doc.getDbValue("email")
+      if (dbEmail && doc.get("email") !== dbEmail) {
+        frappe.throw("Email cannot be changed after creation")
+      }
+    }
+  },
+})

package/src/core/doctype/user/user.ts

@@ -0,0 +1,22 @@
+export default doctype("User", {
+  naming: "field:email",
+  module: "Core",
+  fields: {
+    email: field.data({ options: "Email", required: true, unique: true }),
+    fullName: field.data({ required: true }),
+    enabled: field.check({ default: 1 }),
+    password: field.password(),
+    language: field.data({ default: "en" }),
+    userType: field.select(["System User", "Website User"], { default: "System User" }),
+    lastLogin: field.datetime({ readOnly: true }),
+    lastActiveAt: field.datetime({ readOnly: true }),
+    apiKey: field.data({ readOnly: true }),
+    apiSecret: field.password({ readOnly: true }),
+  },
+  permissions: [{ role: "System Manager", read: true, write: true, create: true, delete: true }],
+  list: {
+    fields: ["email", "fullName", "enabled", "userType"],
+    titleField: "fullName",
+    searchFields: ["email", "fullName"],
+  },
+})

package/src/core/doctype/user_role/user_role.ts

@@ -0,0 +1,9 @@
+export default doctype("UserRole", {
+  naming: "autoincrement",
+  module: "Core",
+  isChild: true,
+  fields: {
+    user: field.link("User", { required: true }),
+    role: field.link("Role", { required: true }),
+  },
+})

package/src/core/doctypes.ts

@@ -0,0 +1,25 @@
+/**
+ * Core DocTypes registration via filesystem discovery.
+ */
+
+import { join, dirname } from "node:path"
+
+import { discoverDocTypes } from "../doctype/discovery"
+import { hasDocType } from "../doctype/registry"
+import { installGlobals } from "../globals"
+
+/** Path to the core doctype/ directory (sibling to this file). */
+const CORE_DOCTYPE_DIR = join(dirname(import.meta.path), "doctype")
+
+/**
+ * Register all core DocTypes by scanning src/core/doctype/.
+ * Safe to call multiple times — skips if already registered.
+ */
+export async function registerCoreDocTypes(): Promise<void> {
+  if (hasDocType("User")) return
+
+  // Ensure ambient globals are available for schema files
+  installGlobals()
+
+  await discoverDocTypes(CORE_DOCTYPE_DIR)
+}

package/src/core/index.ts

@@ -0,0 +1 @@
+export { registerCoreDocTypes } from "./doctypes"

package/src/database/database.ts

@@ -0,0 +1,359 @@
+/**
+ * Database abstraction — wraps bun:sqlite, provides the frappe.db API.
+ */
+
+import { Database as BunSQLite } from "bun:sqlite"
+import type { SQLQueryBindings } from "bun:sqlite"
+
+import { toTableName } from "../doctype/registry"
+import type { Dict, FilterInput } from "../doctype/types"
+import { parseFilters } from "./filters"
+import { QueryBuilder, emptyState } from "./query-builder"
+import { syncSchema } from "./schema"
+
+/** A single binding value accepted by bun:sqlite. */
+type Binding = SQLQueryBindings
+/** An ordered list of bindings for a parameterized query. */
+type Bindings = Binding[]
+
+/** Run a statement with optional bindings. Returns the number of affected rows. */
+function stmt(db: BunSQLite, sql: string, bindings?: Bindings): number {
+  const result = bindings && bindings.length > 0 ? db.run(sql, bindings) : db.run(sql)
+  return result.changes
+}
+
+export interface GetAllArgs {
+  filters?: FilterInput
+  fields?: string[]
+  orderBy?: string
+  limit?: number
+  offset?: number
+}
+
+interface SeriesRow {
+  current: number
+}
+interface MaxIdRow {
+  maxId: number | null
+}
+
+export class FrappeDatabase {
+  private readonly db: BunSQLite
+  private readonly debugMode: boolean
+
+  constructor(dbPath: string, opts?: { debug?: boolean }) {
+    this.db = new BunSQLite(dbPath, { create: true })
+    this.db.run("PRAGMA journal_mode = WAL")
+    this.db.run("PRAGMA foreign_keys = ON")
+    this.debugMode = opts?.debug ?? false
+  }
+
+  /** The raw bun:sqlite instance — for advanced use only. */
+  get raw(): BunSQLite {
+    return this.db
+  }
+
+  // ─── High-level API (frappe.db.*) ──────────────────────────
+
+  /**
+   * Get a single field value, multiple field values, or null if not found.
+   *
+   * Single field:   `getValue("User", "admin", "fullName")       → unknown`
+   * Multiple fields: `getValue("User", "admin", ["name","email"]) → Dict | null`
+   * With filter:    `getValue("User", { email: "a@b.com" }, "fullName")`
+   */
+  async getValue(
+    doctype: string,
+    nameOrFilters: string | FilterInput,
+    field: string,
+  ): Promise<unknown>
+  async getValue(
+    doctype: string,
+    nameOrFilters: string | FilterInput,
+    fields: string[],
+  ): Promise<Dict | null>
+  async getValue(
+    doctype: string,
+    nameOrFilters: string | FilterInput,
+    fieldOrFields: string | string[],
+  ): Promise<unknown> {
+    const fields = Array.isArray(fieldOrFields) ? fieldOrFields : [fieldOrFields]
+    let qb = this.qb(doctype).select(...fields)
+
+    if (typeof nameOrFilters === "string") {
+      qb = qb.where("name", nameOrFilters)
+    } else {
+      qb = qb.where(nameOrFilters)
+    }
+
+    const row = await qb.limit(1).first<Dict>()
+    if (row == null) return null
+    if (Array.isArray(fieldOrFields)) return row
+    return row[fieldOrFields as string]
+  }
+
+  /**
+   * Get multiple documents matching optional filters.
+   */
+  async getAll(doctype: string, args: GetAllArgs = {}): Promise<Dict[]> {
+    const { filters, fields = ["name"], orderBy = "modified DESC", limit = 20, offset = 0 } = args
+
+    let qb = this.qb(doctype)
+      .select(...fields)
+      .limit(limit)
+      .offset(offset)
+
+    if (filters) qb = qb.where(filters)
+
+    // Parse "field DIR" orderBy string
+    const [orderField, orderDir] = (orderBy as string).split(/\s+/, 2)
+    if (orderField) {
+      qb = qb.orderBy(orderField, (orderDir ?? "asc").toLowerCase() as "asc" | "desc")
+    }
+
+    return qb.all<Dict>()
+  }
+
+  /**
+   * Check whether a document exists.
+   */
+  async exists(doctype: string, nameOrFilters: string | FilterInput): Promise<boolean> {
+    let qb = this.qb(doctype)
+    if (typeof nameOrFilters === "string") {
+      qb = qb.where("name", nameOrFilters)
+    } else {
+      qb = qb.where(nameOrFilters)
+    }
+    return qb.exists()
+  }
+
+  /**
+   * Count documents matching optional filters.
+   */
+  async count(doctype: string, filters?: FilterInput): Promise<number> {
+    let qb = this.qb(doctype)
+    if (filters) qb = qb.where(filters)
+    return qb.count()
+  }
+
+  /**
+   * Set one or more fields on a document by name.
+   */
+  async setValue(doctype: string, name: string, field: string, value: unknown): Promise<void>
+  async setValue(doctype: string, name: string, updates: Dict): Promise<void>
+  async setValue(
+    doctype: string,
+    name: string,
+    fieldOrUpdates: string | Dict,
+    value?: unknown,
+  ): Promise<void> {
+    const updates: Dict =
+      typeof fieldOrUpdates === "string"
+        ? { [fieldOrUpdates]: value, modified: new Date().toISOString() }
+        : { ...fieldOrUpdates, modified: new Date().toISOString() }
+
+    // Build SET clause via direct SQL — the QB handles SELECT/WHERE but not
+    // arbitrary multi-field UPDATE, so we use the row-level helper here.
+    this.updateRow(toTableName(doctype), name, updates)
+  }
+
+  /**
+   * Delete documents by name or filter.
+   */
+  async delete(doctype: string, nameOrFilters: string | FilterInput): Promise<number> {
+    const tableName = toTableName(doctype)
+    const { sql: whereSql, values } =
+      typeof nameOrFilters === "string"
+        ? { sql: `"name" = ?`, values: [nameOrFilters] }
+        : parseFilters(nameOrFilters)
+    return stmt(this.db, `DELETE FROM "${tableName}" WHERE ${whereSql}`, values as Bindings)
+  }
+
+  /**
+   * Bulk update documents matching filters.
+   */
+  async bulkUpdate(doctype: string, args: { filters: FilterInput; update: Dict }): Promise<number> {
+    const tableName = toTableName(doctype)
+    const updates = { ...args.update, modified: new Date().toISOString() }
+    const { sql: whereSql, values: whereValues } = parseFilters(args.filters)
+
+    const setClauses = Object.keys(updates)
+      .map((k) => `"${k}" = ?`)
+      .join(", ")
+    const bindings: Bindings = [
+      ...(Object.values(updates) as Binding[]),
+      ...(whereValues as Binding[]),
+    ]
+    return stmt(this.db, `UPDATE "${tableName}" SET ${setClauses} WHERE ${whereSql}`, bindings)
+  }
+
+  // ─── Raw SQL ──────────────────────────────────────────────
+
+  /**
+   * Execute a raw parameterized query. Returns typed rows.
+   */
+  async sql<T extends Record<string, unknown> = Dict>(
+    query: string,
+    values?: Bindings,
+    opts?: { debug?: boolean },
+  ): Promise<T[]> {
+    if (opts?.debug || this.debugMode) this.log(query, values)
+    return values && values.length > 0
+      ? this.db.query<T, Bindings>(query).all(...values)
+      : this.db.query<T, []>(query).all()
+  }
+
+  // ─── Transactions ─────────────────────────────────────────
+
+  async commit(): Promise<void> {
+    // SQLite in WAL mode auto-commits. No-op outside explicit transactions.
+  }
+
+  async rollback(): Promise<void> {
+    // Rollback is handled via savepoints.
+  }
+
+  async savepoint<T>(name: string, fn: () => Promise<T>): Promise<T> {
+    this.db.run(`SAVEPOINT "${name}"`)
+    try {
+      const result = await fn()
+      this.db.run(`RELEASE SAVEPOINT "${name}"`)
+      return result
+    } catch (error) {
+      this.db.run(`ROLLBACK TO SAVEPOINT "${name}"`)
+      throw error
+    }
+  }
+
+  async transaction<T>(fn: () => Promise<T>): Promise<T> {
+    this.db.run("BEGIN")
+    try {
+      const result = await fn()
+      this.db.run("COMMIT")
+      return result
+    } catch (error) {
+      this.db.run("ROLLBACK")
+      throw error
+    }
+  }
+
+  // ─── Schema ───────────────────────────────────────────────
+
+  /**
+   * Sync all registered DocType schemas to the database.
+   * Creates missing tables and adds missing columns.
+   */
+  migrate(): void {
+    syncSchema(this.db)
+  }
+
+  /**
+   * Rename a column on a DocType's table.
+   * Used by before-sync migrations when a field is being renamed —
+   * must run before the auto schema-sync drops or re-adds the column.
+   */
+  async renameField(doctype: string, oldName: string, newName: string): Promise<void> {
+    const table = toTableName(doctype)
+    this.db.run(`ALTER TABLE "${table}" RENAME COLUMN "${oldName}" TO "${newName}"`)
+  }
+
+  /**
+   * Rename a DocType's underlying table and update Link field references
+   * in sibling tables. Called from before-sync migrations.
+   */
+  async renameDocType(oldName: string, newName: string): Promise<void> {
+    const oldTable = toTableName(oldName)
+    const newTable = toTableName(newName)
+    this.db.run(`ALTER TABLE "${oldTable}" RENAME TO "${newTable}"`)
+  }
+
+  // ─── Query Builder factory ────────────────────────────────
+
+  /**
+   * Create a QueryBuilder bound to this database for the given DocType.
+   * Called internally by frappe.db.* methods and exposed via frappe.query().
+   */
+  qb(doctype: string): QueryBuilder {
+    return new QueryBuilder(this.db, emptyState(doctype))
+  }
+
+  // ─── Row-level helpers (used by Document) ─────────────────
+
+  insertRow(tableName: string, data: Dict): void {
+    const keys = Object.keys(data)
+    const placeholders = keys.map(() => "?").join(", ")
+    const fieldList = keys.map((k) => `"${k}"`).join(", ")
+    const bindings = Object.values(data) as Bindings
+    stmt(this.db, `INSERT INTO "${tableName}" (${fieldList}) VALUES (${placeholders})`, bindings)
+  }
+
+  updateRow(tableName: string, name: string, data: Dict): void {
+    const keys = Object.keys(data).filter((k) => k !== "name")
+    if (keys.length === 0) return
+
+    const setClauses = keys.map((k) => `"${k}" = ?`).join(", ")
+    const bindings: Bindings = [...(keys.map((k) => data[k]) as Binding[]), name]
+    stmt(this.db, `UPDATE "${tableName}" SET ${setClauses} WHERE "name" = ?`, bindings)
+  }
+
+  deleteRow(tableName: string, name: string): void {
+    this.db.run(`DELETE FROM "${tableName}" WHERE "name" = ?`, [name])
+  }
+
+  deleteChildren(tableName: string, parent: string, parentField: string): void {
+    this.db.run(`DELETE FROM "${tableName}" WHERE "parent" = ? AND "parentField" = ?`, [
+      parent,
+      parentField,
+    ])
+  }
+
+  getRow(tableName: string, name: string): Dict | null {
+    return this.db.query<Dict, [string]>(`SELECT * FROM "${tableName}" WHERE "name" = ?`).get(name)
+  }
+
+  getChildren(tableName: string, parent: string, parentField: string): Dict[] {
+    return this.db
+      .query<Dict, [string, string]>(
+        `SELECT * FROM "${tableName}" WHERE "parent" = ? AND "parentField" = ? ORDER BY "idx" ASC`,
+      )
+      .all(parent, parentField)
+  }
+
+  getNextId(tableName: string): number {
+    const row = this.db
+      .query<MaxIdRow, []>(`SELECT MAX(CAST("name" AS INTEGER)) as maxId FROM "${tableName}"`)
+      .get()
+    return (row?.maxId ?? 0) + 1
+  }
+
+  getNextSeries(seriesPattern: string): string {
+    const hashCount = (seriesPattern.match(/#/g) ?? []).length
+    const seriesPrefix = seriesPattern.replace(/#+$/, "")
+
+    this.db.run(
+      `CREATE TABLE IF NOT EXISTS "_Series" ("name" VARCHAR(140) PRIMARY KEY, "current" INTEGER DEFAULT 0)`,
+    )
+
+    const existing = this.db
+      .query<SeriesRow, [string]>(`SELECT "current" FROM "_Series" WHERE "name" = ?`)
+      .get(seriesPrefix)
+
+    const next = (existing?.current ?? 0) + 1
+
+    if (existing) {
+      this.db.run(`UPDATE "_Series" SET "current" = ? WHERE "name" = ?`, [next, seriesPrefix])
+    } else {
+      this.db.run(`INSERT INTO "_Series" ("name", "current") VALUES (?, ?)`, [seriesPrefix, next])
+    }
+
+    return `${seriesPrefix}${String(next).padStart(hashCount || 5, "0")}`
+  }
+
+  close(): void {
+    this.db.close()
+  }
+
+  private log(sql: string, values?: Bindings): void {
+    if (this.debugMode) console.log(`[SQL] ${sql}`, values?.length ? values : "")
+  }
+}