frappebun 0.0.0

package/src/document/document.ts

@@ -0,0 +1,593 @@
+/**
+ * Document class — runtime instance of a DocType row.
+ * Handles CRUD, lifecycle hooks, child tables, and computed fields.
+ */
+
+import type { FrappeDatabase } from "../database/database"
+import { getDocTypeMeta, getController, toTableName } from "../doctype/registry"
+import type {
+  Dict,
+  DocTypeDefinition,
+  ControllerHooks,
+  DocumentLike,
+  FilterInput,
+} from "../doctype/types"
+import {
+  DoesNotExistError,
+  DuplicateEntryError,
+  TimestampMismatchError,
+  ValidationError,
+} from "../errors"
+import { generateName } from "./naming"
+
+// ─── Standard field names (set directly on the instance) ──
+
+const STANDARD_PROPS = new Set([
+  "name",
+  "doctype",
+  "owner",
+  "creation",
+  "modified",
+  "modifiedBy",
+  "docstatus",
+  "idx",
+  "parent",
+  "parentType",
+  "parentField",
+])
+
+// ─── Document ─────────────────────────────────────────────
+
+export class Document implements DocumentLike {
+  // Identity
+  name!: string
+  readonly doctype: string
+
+  // Standard fields (auto-managed)
+  owner: string = ""
+  creation: string = ""
+  modified: string = ""
+  modifiedBy: string = ""
+  docstatus: 0 | 1 | 2 = 0
+  idx: number = 0
+
+  // Child table fields (only present on child documents)
+  parent?: string
+  parentType?: string
+  parentField?: string
+
+  // ── Internal state (prefixed to avoid field name conflicts) ──
+  _isNew: boolean = true
+  _originalValues: Dict = {}
+  _db!: FrappeDatabase
+  _user: string = "Guest"
+  _meta!: DocTypeDefinition
+  _controller?: ControllerHooks
+  _dynFields: Dict = {}
+
+  constructor(doctype: string) {
+    this.doctype = doctype
+  }
+
+  // ── Initialization ─────────────────────────────────────
+
+  _init(db: FrappeDatabase, user: string): void {
+    this._db = db
+    this._user = user
+    this._meta = getDocTypeMeta(this.doctype)!
+    this._controller = getController(this.doctype)
+  }
+
+  _loadValues(data: Dict): void {
+    for (const [key, value] of Object.entries(data)) {
+      this.set(key, value)
+    }
+  }
+
+  _snapshotOriginal(): void {
+    this._originalValues = this.asDict()
+    this._isNew = false
+  }
+
+  // ── State ──────────────────────────────────────────────
+
+  isNew(): boolean {
+    return this._isNew
+  }
+
+  isModified(field?: string): boolean {
+    if (this._isNew) return true
+    if (field) return this.get(field) !== this._originalValues[field]
+    const current = this.asDict()
+    return Object.keys(current).some(
+      (k) => !k.startsWith("_") && current[k] !== this._originalValues[k],
+    )
+  }
+
+  // ── CRUD ───────────────────────────────────────────────
+
+  async insert(): Promise<this> {
+    const { schema } = this._meta
+    const hooks = this._controller
+    const now = new Date().toISOString()
+
+    await hooks?.beforeInsert?.(this)
+    this._setDefaults()
+
+    this.owner = this._user
+    this.creation = now
+    this.modified = now
+    this.modifiedBy = this._user
+
+    if (!this.name) {
+      this.name = generateName(
+        schema.naming ?? "autoincrement",
+        this.doctype,
+        this.asDict(),
+        this._db,
+      )
+    }
+
+    this._runComputed()
+    await hooks?.validate?.(this)
+
+    if (await this._db.exists(this.doctype, this.name)) {
+      throw new DuplicateEntryError(`${this.doctype} "${this.name}" already exists`)
+    }
+
+    this._db.insertRow(toTableName(this.doctype), this.getValidDict())
+    await this._insertChildren()
+
+    await hooks?.afterInsert?.(this)
+    await hooks?.onUpdate?.(this)
+    await hooks?.afterSave?.(this)
+
+    this._snapshotOriginal()
+    return this
+  }
+
+  async save(): Promise<this> {
+    if (this._isNew) return this.insert()
+
+    const hooks = this._controller
+    const now = new Date().toISOString()
+
+    this.modified = now
+    this.modifiedBy = this._user
+
+    // Optimistic locking
+    const dbModified = await this._db.getValue(this.doctype, this.name, "modified")
+    if (
+      dbModified &&
+      this._originalValues["modified"] &&
+      dbModified !== this._originalValues["modified"]
+    ) {
+      throw new TimestampMismatchError(
+        `${this.doctype} "${this.name}" was modified by another user`,
+      )
+    }
+
+    await hooks?.beforeSave?.(this)
+    this._setDefaults()
+    this._runComputed()
+    await hooks?.validate?.(this)
+
+    this._db.updateRow(toTableName(this.doctype), this.name, this.getValidDict())
+    await this._updateChildren()
+
+    await hooks?.onUpdate?.(this)
+    await hooks?.afterSave?.(this)
+
+    this._snapshotOriginal()
+    return this
+  }
+
+  async submit(): Promise<this> {
+    if (!this._meta.schema.isSubmittable) {
+      throw new ValidationError(`${this.doctype} is not submittable`)
+    }
+
+    const hooks = this._controller
+    await hooks?.beforeSubmit?.(this)
+
+    this.docstatus = 1
+    this._runComputed()
+    await hooks?.validate?.(this)
+
+    const now = new Date().toISOString()
+    this.modified = now
+    this.modifiedBy = this._user
+    this._db.updateRow(toTableName(this.doctype), this.name, this.getValidDict())
+    await this._updateChildren()
+
+    await hooks?.onSubmit?.(this)
+    await hooks?.afterSave?.(this)
+
+    this._snapshotOriginal()
+    return this
+  }
+
+  async cancel(): Promise<this> {
+    if (!this._meta.schema.isSubmittable) {
+      throw new ValidationError(`${this.doctype} is not submittable`)
+    }
+
+    const hooks = this._controller
+    await hooks?.beforeCancel?.(this)
+
+    this.docstatus = 2
+
+    const now = new Date().toISOString()
+    this.modified = now
+    this.modifiedBy = this._user
+    this._db.updateRow(toTableName(this.doctype), this.name, this.getValidDict())
+
+    await hooks?.onCancel?.(this)
+    await hooks?.afterSave?.(this)
+
+    this._snapshotOriginal()
+    return this
+  }
+
+  async delete(): Promise<void> {
+    const hooks = this._controller
+    await hooks?.onTrash?.(this)
+    await this._deleteChildren()
+    this._db.deleteRow(toTableName(this.doctype), this.name)
+  }
+
+  async reload(): Promise<this> {
+    const row = this._db.getRow(toTableName(this.doctype), this.name)
+    if (!row) throw new DoesNotExistError(`${this.doctype} "${this.name}" does not exist`)
+
+    this._dynFields = {}
+    this._loadValues(row)
+    await this._loadChildren()
+    await this._controller?.onLoad?.(this)
+
+    this._snapshotOriginal()
+    return this
+  }
+
+  // ── Field access ────────────────────────────────────────
+
+  get(field: string): unknown {
+    if (STANDARD_PROPS.has(field)) return (this as Record<string, unknown>)[field]
+    return this._dynFields[field]
+  }
+
+  set(field: string, value: unknown): void {
+    if (STANDARD_PROPS.has(field)) {
+      ;(this as Record<string, unknown>)[field] = value
+    } else {
+      this._dynFields[field] = value
+    }
+  }
+
+  async getDbValue(field: string): Promise<unknown> {
+    if (this._isNew) return undefined
+    return this._db.getValue(this.doctype, this.name, field)
+  }
+
+  // ── Child table helpers ─────────────────────────────────
+
+  append(fieldName: string, data?: Dict): Document {
+    const fieldDef = this._meta.schema.fields[fieldName]
+    if (!fieldDef || fieldDef.type !== "Table") {
+      throw new ValidationError(`"${fieldName}" is not a table field on ${this.doctype}`)
+    }
+
+    const children = (this.get(fieldName) as Document[] | undefined) ?? []
+
+    const child = new Document(fieldDef.childDocType!)
+    child._init(this._db, this._user)
+    child.parent = this.name
+    child.parentType = this.doctype
+    child.parentField = fieldName
+    child.idx = children.length + 1
+    if (data) child._loadValues(data)
+
+    children.push(child)
+    this.set(fieldName, children)
+    return child
+  }
+
+  remove(fieldName: string, row: DocumentLike): void {
+    const children = this.get(fieldName) as Document[] | undefined
+    if (!children) return
+
+    const idx = children.indexOf(row as Document)
+    if (idx !== -1) {
+      children.splice(idx, 1)
+      children.forEach((child, i) => {
+        child.idx = i + 1
+      })
+    }
+  }
+
+  async addComment(_text: string, _commentType?: string): Promise<void> {
+    // Placeholder — will be wired to a Comment DocType in a later layer
+  }
+
+  // ── Serialization ───────────────────────────────────────
+
+  asDict(): Dict {
+    const dict: Dict = {
+      name: this.name,
+      doctype: this.doctype,
+      owner: this.owner,
+      creation: this.creation,
+      modified: this.modified,
+      modifiedBy: this.modifiedBy,
+      docstatus: this.docstatus,
+      idx: this.idx,
+    }
+
+    if (this.parent !== undefined) dict["parent"] = this.parent
+    if (this.parentType !== undefined) dict["parentType"] = this.parentType
+    if (this.parentField !== undefined) dict["parentField"] = this.parentField
+
+    for (const [fieldName, fieldDef] of Object.entries(this._meta?.schema.fields ?? {})) {
+      const val = this.get(fieldName)
+      if (val === undefined) continue
+
+      if (fieldDef.type === "Table" && Array.isArray(val)) {
+        dict[fieldName] = val.map((child) => (child instanceof Document ? child.asDict() : child))
+      } else {
+        dict[fieldName] = val
+      }
+    }
+
+    return dict
+  }
+
+  getValidDict(): Dict {
+    const dict: Dict = {
+      name: this.name,
+      owner: this.owner,
+      creation: this.creation,
+      modified: this.modified,
+      modifiedBy: this.modifiedBy,
+      docstatus: this.docstatus,
+      idx: this.idx,
+    }
+
+    if (this.parent !== undefined) dict["parent"] = this.parent
+    if (this.parentType !== undefined) dict["parentType"] = this.parentType
+    if (this.parentField !== undefined) dict["parentField"] = this.parentField
+
+    for (const [fieldName, fieldDef] of Object.entries(this._meta?.schema.fields ?? {})) {
+      if (fieldDef.type === "Table") continue
+      const val = this.get(fieldName)
+      if (val !== undefined) dict[fieldName] = val
+    }
+
+    return dict
+  }
+
+  // ── Private helpers ─────────────────────────────────────
+
+  private _setDefaults(): void {
+    for (const [fieldName, fieldDef] of Object.entries(this._meta?.schema.fields ?? {})) {
+      if (fieldDef.type === "Table") continue
+      const current = this.get(fieldName)
+      if (current !== undefined && current !== null) continue
+      if (fieldDef.default === undefined) continue
+
+      let defaultValue: unknown = fieldDef.default
+      if (defaultValue === "today") {
+        defaultValue = new Date().toISOString().split("T")[0]
+      } else if (defaultValue === "now") {
+        defaultValue = new Date().toISOString()
+      } else if (defaultValue === "__user") {
+        defaultValue = this._user
+      }
+
+      this.set(fieldName, defaultValue)
+    }
+  }
+
+  private _runComputed(): void {
+    for (const [fieldName, fieldDef] of Object.entries(this._meta?.schema.fields ?? {})) {
+      if (fieldDef.computed) {
+        this.set(fieldName, fieldDef.computed(this))
+      }
+    }
+  }
+
+  private async _insertChildren(): Promise<void> {
+    for (const [fieldName, fieldDef] of Object.entries(this._meta?.schema.fields ?? {})) {
+      if (fieldDef.type !== "Table") continue
+      const children = this.get(fieldName)
+      if (!Array.isArray(children)) continue
+
+      const childTableName = toTableName(fieldDef.childDocType!)
+
+      for (const child of children) {
+        const childDoc = this._toChildDoc(child, fieldDef.childDocType!, fieldName)
+        if (!childDoc.name) {
+          childDoc.name = generateName("autoincrement", fieldDef.childDocType!, {}, this._db)
+        }
+        this._db.insertRow(childTableName, childDoc.getValidDict())
+      }
+    }
+  }
+
+  private async _updateChildren(): Promise<void> {
+    for (const [fieldName, fieldDef] of Object.entries(this._meta?.schema.fields ?? {})) {
+      if (fieldDef.type !== "Table") continue
+      const children = this.get(fieldName)
+      if (!Array.isArray(children)) continue
+
+      const childTableName = toTableName(fieldDef.childDocType!)
+      this._db.deleteChildren(childTableName, this.name, fieldName)
+
+      for (const child of children) {
+        const childDoc = this._toChildDoc(child, fieldDef.childDocType!, fieldName)
+        if (!childDoc.name) {
+          childDoc.name = generateName("autoincrement", fieldDef.childDocType!, {}, this._db)
+        }
+        if (!childDoc.owner) {
+          childDoc.owner = this._user
+          childDoc.creation = this.creation
+        }
+        this._db.insertRow(childTableName, childDoc.getValidDict())
+      }
+    }
+  }
+
+  private async _deleteChildren(): Promise<void> {
+    for (const [fieldName, fieldDef] of Object.entries(this._meta?.schema.fields ?? {})) {
+      if (fieldDef.type !== "Table") continue
+      this._db.deleteChildren(toTableName(fieldDef.childDocType!), this.name, fieldName)
+    }
+  }
+
+  private async _loadChildren(): Promise<void> {
+    for (const [fieldName, fieldDef] of Object.entries(this._meta?.schema.fields ?? {})) {
+      if (fieldDef.type !== "Table") continue
+      const rows = this._db.getChildren(toTableName(fieldDef.childDocType!), this.name, fieldName)
+      const children = rows.map((row) => {
+        const child = new Document(fieldDef.childDocType!)
+        child._init(this._db, this._user)
+        child._loadValues(row)
+        child._isNew = false
+        return child
+      })
+      this.set(fieldName, children)
+    }
+  }
+
+  private _toChildDoc(child: unknown, childDocType: string, fieldName: string): Document {
+    if (child instanceof Document) {
+      child.parent = this.name
+      child.parentType = this.doctype
+      child.parentField = fieldName
+      child.modified = this.modified
+      child.modifiedBy = this._user
+      return child
+    }
+
+    // Plain object — wrap it
+    const doc = new Document(childDocType)
+    doc._init(this._db, this._user)
+    doc._loadValues(child as Dict)
+    doc.parent = this.name
+    doc.parentType = this.doctype
+    doc.parentField = fieldName
+    doc.owner = this._user
+    doc.creation = this.creation
+    doc.modified = this.modified
+    doc.modifiedBy = this._user
+    return doc
+  }
+}
+
+// ─── Factory functions ────────────────────────────────────
+
+export function newDoc(
+  doctype: string,
+  data: Dict | undefined,
+  db: FrappeDatabase,
+  user: string,
+): Document {
+  const meta = getDocTypeMeta(doctype)
+  if (!meta) throw new ValidationError(`DocType "${doctype}" is not registered`)
+
+  const doc = new Document(doctype)
+  doc._init(db, user)
+  if (data) doc._loadValues(data)
+  return doc
+}
+
+export async function getDoc(
+  doctype: string,
+  name: string,
+  db: FrappeDatabase,
+  user: string,
+): Promise<Document> {
+  const meta = getDocTypeMeta(doctype)
+  if (!meta) throw new ValidationError(`DocType "${doctype}" is not registered`)
+
+  const row = db.getRow(toTableName(doctype), name)
+  if (!row) throw new DoesNotExistError(`${doctype} "${name}" does not exist`)
+
+  const doc = new Document(doctype)
+  doc._init(db, user)
+  doc._loadValues(row)
+
+  // Load child tables
+  for (const [fieldName, fieldDef] of Object.entries(meta.schema.fields)) {
+    if (fieldDef.type !== "Table") continue
+    const rows = db.getChildren(toTableName(fieldDef.childDocType!), name, fieldName)
+    doc.set(
+      fieldName,
+      rows.map((childRow) => {
+        const child = new Document(fieldDef.childDocType!)
+        child._init(db, user)
+        child._loadValues(childRow)
+        child._snapshotOriginal()
+        return child
+      }),
+    )
+  }
+
+  await getController(doctype)?.onLoad?.(doc)
+  doc._snapshotOriginal()
+  return doc
+}
+
+export async function getList(
+  doctype: string,
+  args: {
+    filters?: FilterInput
+    fields?: string[]
+    orderBy?: string
+    limit?: number
+    offset?: number
+  },
+  db: FrappeDatabase,
+): Promise<Dict[]> {
+  return db.getAll(doctype, args)
+}
+
+export async function deleteDoc(
+  doctype: string,
+  name: string,
+  db: FrappeDatabase,
+  user: string,
+): Promise<void> {
+  const doc = await getDoc(doctype, name, db, user)
+  await doc.delete()
+}
+
+export async function getSingle(
+  doctype: string,
+  fieldOrFields: string | string[] | undefined,
+  db: FrappeDatabase,
+  user: string,
+): Promise<unknown> {
+  const meta = getDocTypeMeta(doctype)
+  if (!meta?.schema.isSingle) throw new ValidationError(`"${doctype}" is not a Single DocType`)
+
+  const row = db.getRow(toTableName(doctype), doctype)
+  if (!row) {
+    const doc = newDoc(doctype, { name: doctype }, db, user)
+    await doc.insert()
+    return getSingle(doctype, fieldOrFields, db, user)
+  }
+
+  if (!fieldOrFields) {
+    const doc = new Document(doctype)
+    doc._init(db, user)
+    doc._loadValues(row)
+    doc._snapshotOriginal()
+    return doc
+  }
+
+  if (typeof fieldOrFields === "string") return row[fieldOrFields]
+
+  const result: Dict = {}
+  for (const f of fieldOrFields) result[f] = row[f]
+  return result
+}

package/src/document/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Document module — re-exports everything.
+ */
+
+export { Document, newDoc, getDoc, getList, deleteDoc, getSingle } from "./document"
+export { generateName } from "./naming"

package/src/document/naming.ts

@@ -0,0 +1,56 @@
+/**
+ * Name generation strategies for documents.
+ */
+
+import { randomUUIDv7 } from "bun"
+import { createHash } from "node:crypto"
+
+import type { FrappeDatabase } from "../database/database"
+import { toTableName } from "../doctype/registry"
+import type { NamingStrategy, Dict } from "../doctype/types"
+
+/**
+ * Generate a name for a new document based on the DocType's naming strategy.
+ */
+export function generateName(
+  strategy: NamingStrategy,
+  doctype: string,
+  data: Dict,
+  db: FrappeDatabase,
+): string {
+  if (strategy === "uuid") {
+    return randomUUIDv7()
+  }
+
+  if (strategy === "hash") {
+    const hash = createHash("sha256")
+      .update(`${doctype}-${Date.now()}-${Math.random()}`)
+      .digest("hex")
+    return hash.substring(0, 10)
+  }
+
+  if (strategy === "autoincrement") {
+    const tableName = toTableName(doctype)
+    return String(db.getNextId(tableName))
+  }
+
+  if (strategy === "prompt") {
+    const name = data["name"]
+    if (!name) throw new Error(`DocType "${doctype}" requires a name (naming: "prompt")`)
+    return String(name)
+  }
+
+  if (strategy.startsWith("field:")) {
+    const fieldName = strategy.slice(6)
+    const value = data[fieldName]
+    if (!value) throw new Error(`DocType "${doctype}" naming "field:${fieldName}": field is empty`)
+    return String(value)
+  }
+
+  if (strategy.startsWith("series:")) {
+    const pattern = strategy.substring(7)
+    return db.getNextSeries(pattern)
+  }
+
+  throw new Error(`Unknown naming strategy: ${strategy}`)
+}

package/src/errors.ts

@@ -0,0 +1,53 @@
+/**
+ * Frappe error types that map to HTTP status codes.
+ */
+
+export class FrappeError extends Error {
+  httpStatus: number = 500
+  title?: string
+
+  constructor(message: string, title?: string) {
+    super(message)
+    this.name = this.constructor.name
+    this.title = title
+  }
+}
+
+export class ValidationError extends FrappeError {
+  override httpStatus = 417
+}
+
+export class PermissionError extends FrappeError {
+  override httpStatus = 403
+}
+
+export class AuthenticationError extends FrappeError {
+  override httpStatus = 401
+}
+
+export class DoesNotExistError extends FrappeError {
+  override httpStatus = 404
+}
+
+export class DuplicateEntryError extends FrappeError {
+  override httpStatus = 409
+}
+
+export class TimestampMismatchError extends FrappeError {
+  override httpStatus = 409
+}
+
+export class RateLimitError extends FrappeError {
+  override httpStatus = 429
+}
+
+/** Map of error class constructors for use with frappe.throw() */
+export const ErrorTypes = {
+  ValidationError,
+  PermissionError,
+  AuthenticationError,
+  DoesNotExistError,
+  DuplicateEntryError,
+  TimestampMismatchError,
+  RateLimitError,
+} as const