frappebun 0.0.0

package/src/doctype/types.ts

@@ -0,0 +1,407 @@
+/**
+ * TypeScript types for DocType schema definitions.
+ */
+
+import type { QueryBuilderLike } from "./query-builder-stub"
+
+export type Dict = Record<string, unknown>
+
+// ─── Filter types ─────────────────────────────────────────
+
+export type FilterValue = string | number | boolean | null
+export type FilterOperator =
+  | "="
+  | "!="
+  | ">"
+  | "<"
+  | ">="
+  | "<="
+  | "like"
+  | "not like"
+  | "in"
+  | "not in"
+  | "between"
+  | "is"
+export type FilterCondition = [FilterOperator, FilterValue | FilterValue[]]
+export type ObjectFilter = Record<string, FilterValue | FilterCondition | null>
+// ArrayFilter is recursive; using a flat tuple + rest keeps TypeScript happy
+export type ArrayFilter = [string, ...(ObjectFilter | ArrayFilter | unknown)[]]
+export type FilterInput = ObjectFilter | ArrayFilter | null | undefined
+
+// ─── Document interface (for hooks & computed fields) ──────
+
+/**
+ * The document API surface exposed to controllers and field functions.
+ * The concrete `Document` class implements this.
+ */
+export interface DocumentLike {
+  readonly name: string
+  readonly doctype: string
+  owner: string
+  creation: string
+  modified: string
+  modifiedBy: string
+  docstatus: 0 | 1 | 2
+  idx: number
+  parent?: string
+  parentType?: string
+  parentField?: string
+
+  isNew(): boolean
+  isModified(field?: string): boolean
+
+  get(field: string): unknown
+  set(field: string, value: unknown): void
+  getDbValue(field: string): Promise<unknown>
+
+  insert(): Promise<this>
+  save(): Promise<this>
+  submit(): Promise<this>
+  cancel(): Promise<this>
+  delete(): Promise<void>
+  reload(): Promise<this>
+
+  append(field: string, data?: Dict): DocumentLike
+  remove(field: string, row: DocumentLike): void
+  addComment(text: string, commentType?: string): Promise<void>
+
+  asDict(): Dict
+  getValidDict(): Dict
+}
+
+// ─── Field Types ──────────────────────────────────────────
+
+export type FieldType =
+  | "Data"
+  | "Int"
+  | "Float"
+  | "Currency"
+  | "Percent"
+  | "Check"
+  | "Rating"
+  | "Text"
+  | "SmallText"
+  | "LongText"
+  | "TextEditor"
+  | "MarkdownEditor"
+  | "Code"
+  | "HtmlEditor"
+  | "JSON"
+  | "Date"
+  | "Datetime"
+  | "Time"
+  | "Duration"
+  | "Select"
+  | "Link"
+  | "DynamicLink"
+  | "TableMultiSelect"
+  | "Table"
+  | "Attach"
+  | "AttachImage"
+  | "Image"
+  | "Color"
+  | "Signature"
+  | "Geolocation"
+  | "Password"
+  | "ReadOnly"
+  | "HtmlField"
+
+export interface FieldOptions {
+  label?: string
+  required?: boolean
+  unique?: boolean
+  default?: unknown
+  readOnly?: boolean
+  hidden?: boolean
+  description?: string
+  maxLength?: number
+  options?: string
+
+  // List/filter settings
+  inListView?: boolean
+  inStandardFilter?: boolean
+  inGlobalSearch?: boolean
+
+  // Fetch from linked doc
+  fetchFrom?: string
+
+  // Numeric options
+  nonNegative?: boolean
+  precision?: number
+
+  // Computed field — runs on every save
+  computed?: (doc: DocumentLike) => unknown
+
+  // Conditional visibility
+  visibleIf?: (doc: DocumentLike) => boolean
+}
+
+export interface FieldDefinition {
+  type: FieldType
+  label?: string
+  required?: boolean
+  unique?: boolean
+  default?: unknown
+  readOnly?: boolean
+  hidden?: boolean
+  description?: string
+  maxLength?: number
+  options?: string | string[]
+
+  inListView?: boolean
+  inStandardFilter?: boolean
+  inGlobalSearch?: boolean
+  fetchFrom?: string
+  nonNegative?: boolean
+  precision?: number
+  computed?: (doc: DocumentLike) => unknown
+  visibleIf?: (doc: DocumentLike) => boolean
+
+  // For Link fields
+  doctype?: string
+
+  // For DynamicLink fields
+  linkField?: string
+
+  // For Table fields
+  childDocType?: string
+  childFields?: Record<string, FieldDefinition>
+
+  // For Select fields
+  selectOptions?: string[]
+}
+
+// ─── Layout Types ──────────────────────────────────────────
+
+export interface LayoutColumn {
+  _type: "column"
+  fields: string[]
+}
+
+export interface LayoutSection {
+  _type: "section"
+  title?: string
+  collapsible?: boolean
+  description?: string
+  columns?: LayoutColumn[]
+  fields?: string[]
+}
+
+export interface LayoutTab {
+  _type: "tab"
+  label: string
+  sections: LayoutSection[]
+}
+
+export type LayoutEntry = LayoutSection | LayoutTab | string[]
+
+// ─── Permission Types ──────────────────────────────────────
+
+export interface PermissionRule {
+  role: string
+  read?: boolean
+  write?: boolean
+  create?: boolean
+  delete?: boolean
+  submit?: boolean
+  cancel?: boolean
+  amend?: boolean
+  print?: boolean
+  email?: boolean
+  report?: boolean
+  import?: boolean
+  export?: boolean
+  share?: boolean
+  condition?: Dict
+}
+
+// ─── List Configuration ─────────────────────────────────────
+
+export interface ListConfig {
+  fields?: string[]
+  filters?: string[]
+  orderBy?: string
+  titleField?: string
+  searchFields?: string[]
+  subjectField?: string
+}
+
+// ─── Search Configuration ───────────────────────────────────
+
+export interface SearchConfig {
+  indexed?: string[]
+  boost?: Record<string, number>
+}
+
+// ─── Workflow ───────────────────────────────────────────────
+
+export interface WorkflowState {
+  name: string
+  style?: "secondary" | "warning" | "success" | "danger" | "info" | "primary"
+}
+
+export interface WorkflowTransition {
+  from: string
+  to: string
+  by: string
+  action: string
+}
+
+export interface WorkflowConfig {
+  stateField: string
+  states: WorkflowState[]
+  transitions: WorkflowTransition[]
+}
+
+// ─── DocType Schema ─────────────────────────────────────────
+
+export type NamingStrategy =
+  | "autoincrement"
+  | "uuid"
+  | "hash"
+  | "prompt"
+  | `series:${string}`
+  | `field:${string}`
+
+export interface RestConfig {
+  list?: boolean
+  read?: boolean
+  create?: boolean
+  update?: boolean
+  delete?: boolean
+  submit?: boolean
+  cancel?: boolean
+}
+
+export interface DocTypeSchema {
+  naming?: NamingStrategy
+  module?: string
+  isSingle?: boolean
+  isSubmittable?: boolean
+  isTree?: boolean
+  isVirtual?: boolean
+  isChild?: boolean
+  trackChanges?: boolean
+
+  fields: Record<string, FieldDefinition>
+  layout?: LayoutEntry[]
+  permissions?: PermissionRule[]
+  list?: ListConfig
+  search?: SearchConfig
+  workflow?: WorkflowConfig
+
+  /**
+   * Expose this DocType over the REST API.
+   * `true` enables all endpoints; an object selectively enables specific operations.
+   */
+  rest?: boolean | RestConfig
+}
+
+export interface DocTypeDefinition {
+  name: string
+  schema: DocTypeSchema
+}
+
+// ─── Permissions Block (in controller) ──────────────────────
+
+/** Returned by `frappe.perms.deny(message)` to signal a contextual denial. */
+export interface PermissionDenial {
+  __type: "PermissionDenial"
+  message: string
+}
+
+export type PermCheckResult = boolean | PermissionDenial | Promise<boolean | PermissionDenial>
+
+export interface PermissionsBlock {
+  /**
+   * Row-level scope: return a QueryBuilder to restrict the list, or null for no restriction.
+   * Called on every list query for this DocType.
+   */
+  scope?: (user: string) => QueryBuilderLike | null
+
+  /** Called before `doc.insert()`. Return false / deny() to block. */
+  create?: (user: string) => PermCheckResult
+
+  /** Called after `frappe.getDoc()`. Return false / deny() to block. */
+  read?: (doc: DocumentLike, user: string) => PermCheckResult
+
+  /** Called before `doc.save()`. Return false / deny() to block. */
+  write?: (doc: DocumentLike, user: string) => PermCheckResult
+
+  /** Called before `doc.delete()`. Return false / deny() to block. */
+  delete?: (doc: DocumentLike, user: string) => PermCheckResult
+
+  /** Called before `doc.submit()`. */
+  submit?: (doc: DocumentLike, user: string) => PermCheckResult
+
+  /** Called before `doc.cancel()`. */
+  cancel?: (doc: DocumentLike, user: string) => PermCheckResult
+}
+
+// ─── Controller Types ───────────────────────────────────────
+
+export interface ControllerHooks {
+  beforeInsert?: (doc: DocumentLike) => Promise<void> | void
+  validate?: (doc: DocumentLike) => Promise<void> | void
+  afterInsert?: (doc: DocumentLike) => Promise<void> | void
+  beforeSave?: (doc: DocumentLike) => Promise<void> | void
+  onUpdate?: (doc: DocumentLike) => Promise<void> | void
+  afterSave?: (doc: DocumentLike) => Promise<void> | void
+  beforeSubmit?: (doc: DocumentLike) => Promise<void> | void
+  onSubmit?: (doc: DocumentLike) => Promise<void> | void
+  beforeCancel?: (doc: DocumentLike) => Promise<void> | void
+  onCancel?: (doc: DocumentLike) => Promise<void> | void
+  onTrash?: (doc: DocumentLike) => Promise<void> | void
+  onLoad?: (doc: DocumentLike) => Promise<void> | void
+
+  methods?: Record<string, (doc: DocumentLike, ...args: unknown[]) => Promise<unknown> | unknown>
+
+  /** Permissions block: scope and per-action document checks. */
+  permissions?: PermissionsBlock
+
+  getPermissionQuery?: (user: string) => FilterInput
+  hasPermission?: (doc: DocumentLike, ptype: string, user: string) => boolean | Promise<boolean>
+
+  onTransition?: Record<string, (doc: DocumentLike) => Promise<void> | void>
+
+  // Virtual DocType methods
+  getList?: (args: unknown) => Promise<Dict[]>
+  getCount?: (args: unknown) => Promise<number>
+  loadFromDb?: (doc: DocumentLike) => Promise<void>
+  dbInsert?: (doc: DocumentLike) => Promise<void>
+  dbUpdate?: (doc: DocumentLike) => Promise<void>
+  dbDelete?: (doc: DocumentLike) => Promise<void>
+}
+
+export interface ControllerDefinition {
+  name: string
+  hooks: ControllerHooks
+}
+
+// ─── Reserved field names ───────────────────────────────────
+
+export const RESERVED_FIELD_NAMES = new Set([
+  "name",
+  "owner",
+  "creation",
+  "modified",
+  "modifiedBy",
+  "docstatus",
+  "idx",
+  "parent",
+  "parentType",
+  "parentField",
+  "doctype",
+])
+
+export const STANDARD_FIELDS = [
+  "name",
+  "creation",
+  "modified",
+  "modifiedBy",
+  "owner",
+  "docstatus",
+  "idx",
+] as const
+
+export const CHILD_STANDARD_FIELDS = ["parent", "parentType", "parentField"] as const