@dforge-core/metadata 0.0.34 → 0.0.36

package/src/registers/types.ts

@@ -0,0 +1,141 @@
+// Registers — the authoring shape of `registers.json` and of an A / L column's
+// binding. Mirror of registers.schema.json and docs/business-logic/registers.md §3–4.
+
+/** The four kinds. Each requires and refuses a fixed set of properties. */
+export type RegisterKind = "balance" | "turnover" | "info" | "accounting";
+
+export const REGISTER_KINDS: readonly RegisterKind[] = ["balance", "turnover", "info", "accounting"];
+
+export const isRegisterKind = (value: unknown): value is RegisterKind =>
+	typeof value === "string" && (REGISTER_KINDS as readonly string[]).includes(value);
+
+/** Register codes: lowercase letters, digits and underscores, starting with a letter. */
+export const REGISTER_CODE = /^[a-z][a-z0-9_]*$/;
+
+/** A column name as `registers.json` takes one. */
+export const REGISTER_COLUMN_NAME = /^[a-z_][a-z0-9_]*$/;
+
+/** How much one cached row of a `totals` cache covers. */
+export type RegisterTotalsPeriod = "day" | "month" | "quarter" | "year";
+
+export const REGISTER_TOTALS_PERIODS: readonly RegisterTotalsPeriod[] = ["day", "month", "quarter", "year"];
+
+/** A measured column of the register: one shared column, or one per side on an accounting register. */
+export interface RegisterResourceDef {
+	/** The column, on the state entity / journal / record entity. Not with `debitField` / `creditField`. */
+	field?: string;
+	/** Debit-side column, on an accounting register. Declared with `creditField`. */
+	debitField?: string;
+	creditField?: string;
+	/** Every binding must map it (default true). False for a resource only some writers supply. */
+	required?: boolean;
+	/** Under `recordChangesOnly`: what the resource compares as before any record is in effect. */
+	absentAs?: number | string | boolean;
+	description?: string;
+}
+
+/** The per-period cache (registers.md §8). */
+export interface RegisterTotalsDef {
+	entity: string;
+	period: RegisterTotalsPeriod;
+	/** Column holding the first date of the period a row covers. */
+	periodField: string;
+	/** Account column; required on an accounting register, refused elsewhere. */
+	accountField?: string;
+	/** Which dimensions the cache is grouped by; accounting only; all of them when omitted. */
+	dimensions?: string[];
+	/** Every resource of the register: `inField` + `outField`, or `debitField` + `creditField` on an accounting register. */
+	resources: Record<string, { inField?: string; outField?: string; debitField?: string; creditField?: string }>;
+}
+
+/** Where the chart says which analytic each account carries in which slot. */
+export interface RegisterCompositionDef {
+	entity: string;
+	account: string;
+	slot: string;
+	analytic: string;
+}
+
+/** One declaration of `registers.json`. */
+export interface RegisterDef {
+	kind: RegisterKind;
+	label?: string;
+	description?: string;
+	/** State table (`balance`) or record table (`info`). */
+	entity?: string;
+	/** Movement / posting entity (`balance` optional, `turnover` and `accounting` required). */
+	journal?: string;
+	/** Journal column stamped +1 / −1 (`balance`, `turnover`). */
+	journalDirection?: string;
+	/** Journal column holding each movement's date. */
+	journalDate?: string;
+	/** Record-entity column holding when a record takes effect (`info`). */
+	period?: string;
+	/** Record-entity jsonb column the writing document is stamped into (`info`); makes the register subordinate. */
+	recorder?: string;
+	recordChangesOnly?: boolean;
+	/** Chart of accounts (`accounting`). */
+	chart?: string;
+	lineMode?: "classic" | "compound";
+	/** Posting column pointing at the chart (classic). */
+	account?: string;
+	debitAccount?: string;
+	creditAccount?: string;
+	/** Analytic slot columns in slot order (classic). */
+	analyticFields?: string[];
+	debitAnalyticFields?: string[];
+	creditAnalyticFields?: string[];
+	composition?: RegisterCompositionDef;
+	/** 1–8 column names: the key of the register, on its carrier. */
+	dimensions: string[];
+	/** Two-sided dimensions of a compound register, with the column per side. */
+	sideDimensions?: Record<string, { debitField: string; creditField: string }>;
+	resources: Record<string, RegisterResourceDef>;
+	totals?: RegisterTotalsDef;
+	/** `balance`: may the state go below zero (default false). */
+	allowNegative?: boolean;
+	/** `balance`: create the state row on first movement (default true). */
+	autoCreate?: boolean;
+}
+
+/** `registers.json`: register code → declaration. */
+export type RegistersFile = Record<string, RegisterDef>;
+
+/** A map entry: a column of the row read, or on a compound ledger one column per side. */
+export type RegisterMapValue = string | { debit?: string; credit?: string };
+
+/** `params` of an A / L column bound to a register (registers.md §4). */
+export interface RegisterBindingParams {
+	/** `module_cd.register_cd`. */
+	register?: string;
+	/** The bool column recording the posted state, when not the column itself. */
+	stateField?: string;
+	direction?: "increase" | "decrease";
+	/** Per-row direction from a document value, instead of `direction`. */
+	sign?: { field: string; positive?: unknown[]; negative?: unknown[] };
+	/** Document column (or path / expression) supplying the journal date. */
+	dateField?: string;
+	dateTrunc?: "day" | "month" | "year";
+	lineEntity?: string;
+	lineField?: string;
+	groupLinesBy?: string[];
+	/** Register dimension or resource name → column of the row read. */
+	map?: Record<string, RegisterMapValue>;
+	/** On a line posting: register name → DOCUMENT column. */
+	headerMap?: Record<string, string>;
+	lockedFields?: string[];
+	lockedLineFields?: string[];
+	skipPostingWhenEmpty?: string[];
+	/** Classic ledger: the line's account column. */
+	accountField?: string;
+	debitAccountField?: string;
+	creditAccountField?: string;
+	periodDimField?: string;
+	/** Analytic kind → line column (classic ledger). */
+	analytics?: Record<string, string>;
+	debitAnalytics?: Record<string, string>;
+	creditAnalytics?: Record<string, string>;
+	movementMapping?: Record<string, string>;
+	/** Inline restatement of a register; refused alongside `register`. */
+	registries?: unknown;
+}

package/src/stored-procedures.ts

@@ -72,4 +72,11 @@ export interface SpColumnDef {
 	width?: number;
 	/** Control parameters, the same shape an entity column's `params` takes. */
 	params?: Record<string, unknown>;
+	/**
+	 * Reusable column domain supplying the control, datatype and option list.
+	 * Unqualified resolves within this module, then tenant-created domains;
+	 * `module_cd.domain_cd` binds to that module. Mutually exclusive with
+	 * `fieldTypeCd`, `baseDatatypeCd` and `params`.
+	 */
+	domain?: string;
 }