@dforge-core/metadata 0.0.41 → 0.0.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dforge-core/metadata",
-  "version": "0.0.41",
+  "version": "0.0.43",
   "description": "Canonical dForge authoring registries — field types, base datatypes, column types, traits, data-view kinds and chart types — with derivation helpers. Runtime-dependency-free; the single source of truth shared by editors, the web app and the CLI.",
   "license": "MIT",
   "author": "dForge",
@@ -54,7 +54,7 @@
     "ajv": "^8.20.0",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.10"
+    "vitest": "^5.0.4"
   },
   "scripts": {
     "sync-schemas": "node scripts/sync-schemas.mjs",

package/schemas/entity.schema.json

@@ -192,11 +192,20 @@
 						"type": "array",
 						"minItems": 1,
 						"items": { "type": "string" },
-						"description": "Indexed columns, in order. Install refuses any key other than fields and using - \"columns\", which a unique constraint accepts, included."
+						"description": "Indexed columns, in order. Install refuses any key other than fields, using, unique and where - \"columns\", which a unique constraint accepts, included."
 					},
 					"using": {
 						"enum": ["btree", "hash", "gin", "gist", "brin"],
 						"description": "Index method. Omitted, btree."
+					},
+					"unique": {
+						"type": "boolean",
+						"description": "A unique index. With \"where\" it is unique among the rows the condition selects, which a unique constraint cannot be (unique among the rows that are not deleted)."
+					},
+					"where": {
+						"type": "string",
+						"minLength": 1,
+						"description": "A partial index: SQL condition over the table's columns, e.g. \"is_deleted = false\". Only the rows it selects are indexed, and a query uses the index only when its own filter implies the condition. One condition, without ';', '$' or comments. Changing it rebuilds the index on upgrade."
 					}
 				}
 			}
@@ -209,6 +218,26 @@
 			"$ref": "#/$defs/periodConfig",
 			"description": "Period entity configuration. Requires 'period' trait."
 		},
+		"periodGuards": {
+			"type": "array",
+			"description": "Closed-period locks for a document that posts to no register. Each guard names a period entity, the date the document's period follows from, and the column that references the period. The platform fills that column from the date and makes it a foreign key, so a document is written only into a period that exists and is open, and a period documents refer to cannot be deleted. Not allowed on an extension.",
+			"items": {
+				"type": "object",
+				"required": ["periodEntity", "periodDateField", "periodField", "lockedFields"],
+				"properties": {
+					"periodEntity": { "type": "string", "description": "The period entity ('period' trait): this module's, or another module's as 'module.entity'." },
+					"periodDateField": { "type": "string", "description": "The document's date column the period is resolved from." },
+					"periodField": { "type": "string", "description": "The document's column referencing the period's key (varchar, like the key). Filled by the platform from the date; whatever a writer puts there is replaced." },
+					"periodKeyField": { "type": "string", "default": "period_key", "description": "The period entity's key column. Must be its primary key or unique." },
+					"periodClosedField": { "type": "string", "default": "closed", "description": "The period entity's closed flag." },
+					"lockedFields": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Fields a closed period freezes. Insert and delete are always refused there, and the date is always watched; [\"periodDateField\"] refuses just that, [\"*\"] freezes the whole row." },
+					"lineEntity": { "type": "string", "description": "The document's line entity, guarded through its header's date." },
+					"lineField": { "type": "string", "description": "The line's foreign key to the header." },
+					"lockedLineFields": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Line fields a closed period freezes; [\"*\"] for the whole row. Required with lineEntity." }
+				},
+				"additionalProperties": false
+			}
+		},
 		"accumulation": {
 			"$ref": "#/$defs/accumulationConfig",
 			"description": "Accumulation registry configuration (simple document without lines). Requires 'accumulation' trait."
@@ -330,6 +359,7 @@
 				"map": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "object", "required": ["debit", "credit"], "additionalProperties": false, "properties": { "debit": { "type": "string" }, "credit": { "type": "string" } } } ] }, "description": "Register dimension or resource name -> this document's column carrying it. On an accounting (L) column a resource or dimension the register splits by side maps to { \"debit\": \"<line column>\", \"credit\": \"<line column>\" } instead of one column. Every resource the register declares must be mapped (install refuses otherwise); a dimension left out binds to a column of the same name. Only meaningful with 'register'. On an accumulation (A) column a value may be a one-hop reference path, '<reference column>.<target column>', read through the reference at posting time (off the line when the binding posts from lines), or an expression: a string starting with '=' holding an F-column formula over the same row with one-hop reference reads — \"=COALESCE([transit_warehouse_id], [dest_warehouse_id])\"." },
 				"headerMap": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Register dimension or resource name -> this DOCUMENT's column carrying it, for a binding that posts from LINES. A line binding reads every other value off the line, and a dimension that belongs to the document (a dealer, an organisation, a date) cannot be put on the line: a G column is a same-row expression or an aggregate over a child set, so it cannot read a parent. Explicit rather than a fallback, because 'not on the line, try the header' turns a typo into a silent read of an unrelated header column with the same name. Install refuses: a name on neither table, a field also named in 'map', a column also read off the line by 'map', a column that is part of the line's key, a column 'lockedFields' does not freeze (the posting is keyed by it, so it has to hold still while the document is posted), and a RESOURCE unless the register is 'info' (a quantity from the document would be added once per line; an information register's records replace rather than add). A value may be a one-hop reference path off the document, whose reference key column 'lockedFields' must then freeze, or an expression over the document ('=...', see 'map')." },
 				"groupLinesBy": { "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true, "description": "Line columns whose distinct values each post ONE movement, instead of one per line — a production report posting 'this unit worked today' once per unit with a count of 1. 'map' is then read over a group row: the grouped line columns, every column of the document, and one-hop reads through a reference of either, so an expression may mix the document and the group key. A quoted constant is stamped once per group; a numeric line column mapped to a resource is summed over the group. Install refuses: a binding that posts from the document, an L column, a grouped column the line does not store or 'lockedLineFields' does not freeze, a line column read that is neither grouped nor a summed resource, a non-numeric summed resource, a column both grouped and summed, an ungrouped line resource on an 'info' register, a name both the line and the document carry, and a document column read that 'lockedFields' does not freeze. Accumulation (A) columns only." },
+				"lineDateField": { "type": "string", "description": "A line column dating that line's movement instead of 'dateField' — for lines that happen on days of their own under one document date (a limit card issuing through the month and dated at its end). A line that leaves it empty moves on 'dateField'. With 'periodEntity', each line's period must exist and be open, at posting and unposting and at every write to the line, judged by the date the movement is stamped with (the line's or the document's, after 'dateTrunc'). On an information register that records changes only, two lines may not write one key: post one line per key. Install refuses: a register that keeps no date, a binding that posts from the document, a column that is not a stored 'date' or 'timestamp' without time zone, one 'lockedLineFields' does not freeze, one 'groupLinesBy' omits when lines are grouped, and a binding with 'periodDimField'. Accumulation (A) columns only." },
 				"dateField": { "type": "string", "description": "This document's date column, supplying the date the register stamps on each journal row. Required once the register declares a 'journalDate' — one writer that supplied none would make every balance read as of a date quietly short, across all writers. On an accumulation (A) column it may be a one-hop reference path, '<reference column>.<target column>', or an expression over the document ('=...', see 'map')." },
 				"dateTrunc": { "type": "string", "enum": ["day", "month", "year"], "description": "Takes the date 'dateField' supplies back to the start of its day, month or year before the register stamps it — for a document that carries a time while the register's records sit on whole days. The calendar is the value's as stored; no time zone is applied. Needs 'dateField'. Accumulation (A) columns only." },
 				"skipPostingWhenEmpty": { "type": "array", "items": { "type": "string" }, "description": "THE EXCEPTION, not the normal way to model this — read the guide before declaring it. Register dimensions (by the register's names) whose empty value means THIS POSTING records nothing: the line, or the document when the binding posts from the document. One posting is skipped, never the register and never the document. When that is all the document would have recorded it is left unposted to this register, and the flag is per binding, so its other registers post as usual. An empty dimension NOT listed refuses the posting, naming the row and the dimension. It leaves a document fully posted while some of its lines produced no movement, which usually means the document is modelling two kinds of line in one table: since 'lineEntity' is declared per BINDING, prefer giving each register its own line table (goods lines post to stock, service lines do not) so that every line of each table posts. Declare this only when the distinction is not structural but lives in the data — a batch or serial number filled on some rows and not others — so there is no second table to put those rows in. Accumulation (A) columns only. Formerly skipWhenNull: a package using the old name is refused at install, while a tenant's already-stored params keep being read under it." },
@@ -352,6 +382,7 @@
 			"dependencies": {
 				"headerMap": ["lineEntity"],
 				"groupLinesBy": ["lineEntity"],
+				"lineDateField": ["lineEntity", "dateField"],
 				"dateTrunc": ["dateField"],
 				"lineEntity": ["lineField", "lockedLineFields"],
 				"lineField": ["lineEntity"],

package/schemas/registers.schema.json

@@ -24,7 +24,7 @@
 						"account": false,
 						"debitAccount": false, "creditAccount": false,
 						"debitAnalyticFields": false, "creditAnalyticFields": false,
-						"sideDimensions": false
+						"sideDimensions": false, "analyticTotals": false
 					},
 					"description": "A balance register keeps state, so it needs the entity that holds it. It dates its movements on the journal row under 'journalDate'; 'period' belongs to an information register, whose records ARE the dated thing. Its writer is recorded on the journal row, which is what 'recorder' names for an information register that has no journal."
 				}
@@ -41,7 +41,7 @@
 						"account": false,
 						"debitAccount": false, "creditAccount": false,
 						"debitAnalyticFields": false, "creditAnalyticFields": false,
-						"sideDimensions": false,
+						"sideDimensions": false, "analyticTotals": false,
 						"allowNegative": false,
 						"autoCreate": false
 					},
@@ -60,7 +60,7 @@
 						"account": false,
 						"debitAccount": false, "creditAccount": false,
 						"debitAnalyticFields": false, "creditAnalyticFields": false,
-						"sideDimensions": false,
+						"sideDimensions": false, "analyticTotals": false,
 						"totals": false,
 						"allowNegative": false,
 						"autoCreate": false
@@ -241,6 +241,63 @@
 					}
 				}
 			},
+			"analyticTotals": {
+				"type": "object",
+				"description": "An 'accounting' register's per-period cache keyed by the analytics as well: a cached row is keyed by (account, cached dimensions, analytic slots, period), for the accounts the chart flags. It is what makes a balance READ BY AN ANALYTIC cheap - stock by item and warehouse, settlements by counterparty and contract - which 'totals' leaves to the postings because over a whole ledger the analytics are where the rows are. getAccountBalance / getAccountTurnover read whole periods from it and the part-period at the edge from the postings. Beside 'totals', never instead of it, and in an entity of its own. Like 'totals' it caches the turnover within each period, so a backdated posting touches one row; a write to the journal that was not a posting, or a change to an account's flag, marks it stale until it is rebuilt.",
+				"required": ["entity", "period", "periodField", "accountField", "accountFlag", "analyticFields", "resources"],
+				"additionalProperties": false,
+				"properties": {
+					"entity": {
+						"type": "string",
+						"description": "Entity holding the cached rows. Keyed by ONE surrogate column the platform mints (the 'identity' trait), because a slot or a dimension may be empty and a PRIMARY KEY holds no NULL; the platform keeps a unique index over the cache's own key, NULLS NOT DISTINCT, and merges on it. It carries the account column, a column per cached dimension, the jsonb slot columns, the period column and both columns of every resource."
+					},
+					"period": {
+						"type": "string",
+						"enum": ["day", "month", "quarter", "year"],
+						"description": "How much one cached row covers, as for 'totals'."
+					},
+					"periodField": {
+						"type": "string",
+						"pattern": "^[a-z_][a-z0-9_]*$",
+						"description": "Column holding the FIRST date of the period a row covers."
+					},
+					"accountField": {
+						"type": "string",
+						"pattern": "^[a-z_][a-z0-9_]*$",
+						"description": "Column holding the account a cached row belongs to. A compound posting folds into two rows, one per side, each with that side's analytics."
+					},
+					"accountFlag": {
+						"type": "string",
+						"pattern": "^[a-z_][a-z0-9_]*$",
+						"description": "A bool column of the register's chart: the accounts where it is true are cached, and no other. Changing it on an account marks the cache stale until it is rebuilt (install, or dforge register rebuild-totals --cache analytic)."
+					},
+					"dimensions": {
+						"type": "array",
+						"items": { "type": "string", "pattern": "^[a-z_][a-z0-9_]*$" },
+						"description": "Which of the register's dimensions the cache is grouped by; omitted, it is all of them. Unlike 'totals' a nullable one may be cached: an empty value is a key value of its own."
+					},
+					"analyticFields": {
+						"type": "array",
+						"minItems": 1,
+						"items": { "type": "string", "pattern": "^[a-z_][a-z0-9_]*$" },
+						"description": "The cache's jsonb columns holding the analytic slots, slot N in the Nth, one per slot a posting side carries (the wider side's count on a compound register). Each holds the analytic's entity and key, which is what a read filters and groups by."
+					},
+					"resources": {
+						"type": "object",
+						"description": "Every resource the register declares, each with its 'debitField' and 'creditField' columns, as for an accounting register's 'totals'.",
+						"minProperties": 1,
+						"additionalProperties": {
+							"type": "object",
+							"required": ["debitField", "creditField"],
+							"additionalProperties": false,
+							"properties": {
+								"debitField": { "type": "string", "pattern": "^[a-z_][a-z0-9_]*$" },
+								"creditField": { "type": "string", "pattern": "^[a-z_][a-z0-9_]*$" }
+							}
+						}
+					}
+				}
+			},
 			"period": {
 				"type": "string",
 				"pattern": "^[a-z_][a-z0-9_]*$",

package/schemas/roles.schema.json

@@ -18,11 +18,14 @@
 				},
 				"rights": {
 					"type": "object",
-					"description": "Entity rights: entity code → rights string",
+					"description": "Security object → rights string. Keys are PREFIX-NAMESPACED so an action and an entity may share a code: a bare key is an entity code in this module ('invoice'), 'module.entity' is an entity owned by a module this one depends on ('parties.party'), 'action:<action_cd>' is an action from this module's ui/actions.json, and 'sp:<sp_cd>' is a stored procedure from logic/stored_procedures.json ('sp:module.sp_cd' for a dependency's), and 'report:<report_cd>' is a report from ui/reports.json ('report:module.report_cd' for a dependency's). A grant on an action written WITHOUT the 'action:' prefix is read as an entity code, resolves to nothing, and is silently dropped at install — action.execute then returns PERMISSION_DENIED.",
+					"propertyNames": {
+						"pattern": "^(action:[A-Za-z_][A-Za-z0-9_-]*|(sp|report):([A-Za-z_][A-Za-z0-9_-]*\\.)?[A-Za-z_][A-Za-z0-9_-]*|([A-Za-z_][A-Za-z0-9_-]*\\.)?[A-Za-z_][A-Za-z0-9_-]*)$"
+					},
 					"additionalProperties": {
 						"type": "string",
 						"pattern": "^[SIUDCE]*$",
-						"description": "Rights: S=Select, I=Insert, U=Update, D=Delete, C=Clone, E=Execute"
+						"description": "Rights: S=Select, I=Insert, U=Update, D=Delete, C=Clone, E=Execute. Entity objects take any of SIUDC; actions, stored procedures and reports take E."
 					}
 				}
 			},

package/src/dsl/builtins.ts

@@ -99,15 +99,15 @@ export const BUILTINS: Builtin[] = [
 	},
 	{
 		name: "getAccountBalance",
-		signature: "getAccountBalance(register, account, filter?, asOf?)",
+		signature: "getAccountBalance(register, account, filter?, asOf?, options?)",
 		returns: "object",
-		doc: "Balance of one account of an accounting register: `{debit, credit, net}` per resource. `filter` narrows by a dimension, or by an analytic kind the ACCOUNT declares — an analytic takes the key alone, or `{ entity, value }` to name one entity of a kind that is a union of several.",
+		doc: "Balance of one account of an accounting register: `{debit, credit, net}` per resource. `filter` narrows by a dimension, or by an analytic kind the ACCOUNT declares — an analytic takes the key alone, or `{ entity, value }` to name one entity of a kind that is a union of several. `options`: `groupBy` (a name or array — returns an array, a row per combination with a non-zero balance), `exclude: { entity, key }` (leaves out that document's postings) and `before` (a moment, exclusive, in place of `asOf`).",
 	},
 	{
 		name: "getAccountTurnover",
-		signature: "getAccountTurnover(register, account, filter, from, to)",
+		signature: "getAccountTurnover(register, account, filter, from, to, options?)",
 		returns: "object",
-		doc: "What moved through one account over an interval: `{debit, credit, net}` per resource. `filter` narrows as in `getAccountBalance` and may be `null`; `from` and `to` are both required.",
+		doc: "What moved through one account over an interval: `{debit, credit, net}` per resource. `filter` narrows as in `getAccountBalance` and may be `null`; `from` and `to` are both required. `options` takes `groupBy` and `exclude` as in `getAccountBalance`; a grouped turnover has a row per combination that moved.",
 	},
 	{
 		name: "getCorrespondence",

package/src/index.ts

@@ -103,6 +103,7 @@ export {
 	type ReportPanel,
 	type Dataset,
 	type ReportQuery,
+	type RegisterSource,
 	type ColumnDef,
 	type ParamDef,
 	type ParamDefBase,

package/src/registers/check-binding.ts

@@ -48,18 +48,36 @@ function checkPosting(params: Raw, ledger: boolean, error: RegisterReporter): vo
 		if (hasKey(params, "groupLinesBy")) {
 			error(["groupLinesBy"], "register-group-lines", "'groupLinesBy' needs lines to group — name the 'lineEntity'.");
 		}
+		if (hasKey(params, "lineDateField")) {
+			error(["lineDateField"], "register-line-date", "'lineDateField' dates the lines a posting is made from — name the 'lineEntity', or date the document with 'dateField'.");
+		}
 	}
 	if (ledger) {
 		if (!lineEntity) {
 			error(["lineEntity"], "register-line", "An L column posts lines: 'lineEntity' and 'lineField' are required.");
 		}
-		for (const key of ["headerMap", "skipPostingWhenEmpty", "dateTrunc", "groupLinesBy"]) {
+		for (const key of ["headerMap", "skipPostingWhenEmpty", "dateTrunc", "groupLinesBy", "lineDateField"]) {
 			if (hasKey(params, key)) {
 				error([key], "register-ledger-only", `'${key}' is read by A columns only.`);
 			}
 		}
 	}
 	const dateField = safeTrim(params.dateField);
+	const lineDateField = safeTrim(params.lineDateField);
+	if (lineEntity && lineDateField && !ledger) {
+		if (!dateField) {
+			error(["dateField"], "register-line-date", "'lineDateField' falls back to the document's 'dateField' for a line with no date — name a 'dateField'.");
+		}
+		if (hasKey(params, "periodDimField")) {
+			error(["lineDateField"], "register-line-date", "'lineDateField' and 'periodDimField' cannot be combined: the period dimension is the document's one period, and a line dated in another month would post under it.");
+		}
+		if (!lockedLines.includes("*") && !lockedLines.includes(lineDateField)) {
+			error(["lockedLineFields"], "register-line-date", `'${lineDateField}' must be in 'lockedLineFields': a posted line re-dated would leave its movement under the old date.`);
+		}
+		if (Array.isArray(params.groupLinesBy) && !stringList(params.groupLinesBy).includes(lineDateField)) {
+			error(["groupLinesBy"], "register-line-date", `'${lineDateField}' must be in 'groupLinesBy': a group posts one movement, which has one date only when its lines share it.`);
+		}
+	}
 	if (hasKey(params, "dateTrunc") && !dateField) {
 		error(["dateTrunc"], "register-date", "'dateTrunc' needs a 'dateField'.");
 	}

package/src/registers/types.ts

@@ -119,6 +119,8 @@ export interface RegisterBindingParams {
 	lineEntity?: string;
 	lineField?: string;
 	groupLinesBy?: string[];
+	/** On a line posting: the line column dating that line's movement instead of `dateField`. */
+	lineDateField?: string;
 	/** Register dimension or resource name → column of the row read. */
 	map?: Record<string, RegisterMapValue>;
 	/** On a line posting: register name → DOCUMENT column. */