@dforge-core/metadata 0.0.36 → 0.0.38

package/package.json

@@ -1,67 +1,68 @@
 {
-  "name": "@dforge-core/metadata",
-  "version": "0.0.36",
-  "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",
-  "homepage": "https://github.com/iash44/dForge-core/tree/main/clients/packages/metadata#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/iash44/dForge-core.git",
-    "directory": "clients/packages/metadata"
-  },
-  "bugs": {
-    "url": "https://github.com/iash44/dForge-core/issues"
-  },
-  "keywords": [
-    "dforge",
-    "metadata",
-    "field-type",
-    "trait",
-    "registry",
-    "low-code"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "type": "module",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "source": "./src/index.ts",
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    },
-    "./dsl": {
-      "source": "./src/dsl/index.ts",
-      "types": "./dist/dsl/index.d.ts",
-      "default": "./dist/dsl/index.js"
-    },
-    "./schemas/*": "./schemas/*",
-    "./package.json": "./package.json"
-  },
-  "sideEffects": false,
-  "files": [
-    "dist",
-    "src",
-    "schemas",
-    "CHANGELOG.md"
-  ],
-  "devDependencies": {
-    "@types/node": "^25.9.4",
-    "ajv": "^8.20.0",
-    "tsup": "^8.5.1",
-    "typescript": "^6.0.3",
-    "vitest": "^4.1.10"
-  },
-  "scripts": {
-    "sync-schemas": "node scripts/sync-schemas.mjs",
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc -p tsconfig.build.json --noEmit",
-    "test": "vitest run",
-    "package": "pnpm pack"
-  }
-}
+	"name": "@dforge-core/metadata",
+	"version": "0.0.38",
+	"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",
+	"homepage": "https://github.com/iash44/dForge-core/tree/main/clients/packages/metadata#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/iash44/dForge-core.git",
+		"directory": "clients/packages/metadata"
+	},
+	"bugs": {
+		"url": "https://github.com/iash44/dForge-core/issues"
+	},
+	"keywords": [
+		"dforge",
+		"metadata",
+		"field-type",
+		"trait",
+		"registry",
+		"low-code"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"type": "module",
+	"main": "./dist/index.js",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"source": "./src/index.ts",
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./dsl": {
+			"source": "./src/dsl/index.ts",
+			"types": "./dist/dsl/index.d.ts",
+			"default": "./dist/dsl/index.js"
+		},
+		"./schemas/*": "./schemas/*",
+		"./package.json": "./package.json"
+	},
+	"sideEffects": false,
+	"files": [
+		"dist",
+		"src",
+		"schemas",
+		"CHANGELOG.md"
+	],
+	"scripts": {
+		"sync-schemas": "node scripts/sync-schemas.mjs",
+		"build": "tsup",
+		"dev": "tsup --watch",
+		"typecheck": "tsc -p tsconfig.build.json --noEmit",
+		"test": "vitest run",
+		"prepack": "pnpm sync-schemas && pnpm typecheck && pnpm build",
+		"package": "pnpm pack"
+	},
+	"devDependencies": {
+		"@types/node": "^25.9.4",
+		"ajv": "^8.20.0",
+		"tsup": "^8.5.1",
+		"typescript": "^6.0.3",
+		"vitest": "^4.1.10"
+	}
+}

package/schemas/demo_vars.schema.json

@@ -0,0 +1,28 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://dforge.dev/schemas/demo_vars.schema.json",
+	"title": "dForge Demo Data Variables",
+	"description": "demo-data/vars.json: the variables demo-data formulas read as @name. A flat map of variable name to value. It is not a data file; the loader skips it, and each module has its own (nothing is shared between modules).",
+	"type": "object",
+	"propertyNames": {
+		"pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
+		"description": "A letter or underscore, then letters, digits or underscores. Names are case-insensitive, and a repeat variable of the same name shadows the file's."
+	},
+	"additionalProperties": {
+		"description": "A plain value (string, number, boolean or null) is substituted as a literal. { \"$f\": \"...\" } is a formula expanded where the variable is used, e.g. { \"$f\": \"DATEADD(TODAY(), -30, 'DAY')\" }; it may read other variables with @name (a cycle fails the install) but not [column] values.",
+		"oneOf": [
+			{ "type": ["string", "number", "boolean", "null"] },
+			{
+				"type": "object",
+				"required": ["$f"],
+				"properties": {
+					"$f": {
+						"type": "string",
+						"description": "Formula whose result is the variable's value"
+					}
+				},
+				"additionalProperties": false
+			}
+		]
+	}
+}

package/schemas/deps.schema.json

@@ -18,12 +18,24 @@
 		},
 		"entities": {
 			"type": "object",
-			"description": "Consumed provider entities, keyed by entity code (e.g. 'party'). At least one, except against a system module (admin, metadata, workspace, sys-billing), where {} declares a pure platform-version gate for a feature that introduced no entity.",
+			"description": "Consumed provider entities, keyed by entity code (e.g. 'party'). At least one, except against a system module (admin, metadata, workspace, sys-billing), where {} declares a pure platform-version gate for a feature that introduced no entity, or when 'functions' imports at least one function.",
 			"additionalProperties": { "$ref": "#/definitions/entityContract" }
+		},
+		"functions": {
+			"type": "array",
+			"description": "The provider's DSL library functions (logic/functions/*.dsl) the consumer's actions call, as <provider code with '-' replaced by '_'>.<name>(...). Only listed names are reachable, and install checks the installed provider declares each. See docs/business-logic/dsl-functions.md.",
+			"items": { "type": "string", "pattern": "^[A-Za-z_$][A-Za-z0-9_$]*$" },
+			"uniqueItems": true,
+			"minItems": 1
 		}
 	},
 	"if": {
-		"not": { "properties": { "module": { "enum": ["admin", "metadata", "workspace", "sys-billing"] } }, "required": ["module"] }
+		"not": {
+			"anyOf": [
+				{ "properties": { "module": { "enum": ["admin", "metadata", "workspace", "sys-billing"] } }, "required": ["module"] },
+				{ "required": ["functions"] }
+			]
+		}
 	},
 	"then": {
 		"properties": { "entities": { "minProperties": 1 } }

package/schemas/settings.schema.json

@@ -4,10 +4,41 @@
 	"title": "dForge Module Settings",
 	"description": "Module-level settings definitions: a flat map of setting code → setting definition. Settings are folder-scoped at runtime (values inherit through the folder tree) and surface in the Module Settings UI.",
 	"type": "object",
+	"propertyNames": {
+		"pattern": "^(\\$constraints|[^$].*)$",
+		"description": "A setting code cannot start with '$'; $constraints is the only reserved key."
+	},
+	"properties": {
+		"$constraints": {
+			"type": "object",
+			"description": "Checks across this module's settings, keyed by constraint name. The settings are the columns of one virtual row, so each is an entity check constraint: SQL over setting codes. settings.set and settings.setMany run every rule naming a written setting, at the folder written and at each folder below it that overrides a setting the rule names; install refuses defaults that fail one. NULL passes, as in a CHECK.",
+			"additionalProperties": {
+				"$ref": "#/$defs/constraint"
+			}
+		}
+	},
 	"additionalProperties": {
 		"$ref": "#/$defs/setting"
 	},
 	"$defs": {
+		"constraint": {
+			"type": "object",
+			"required": ["type", "expression"],
+			"additionalProperties": false,
+			"properties": {
+				"type": {
+					"const": "check"
+				},
+				"expression": {
+					"type": "string",
+					"description": "Boolean over this module's settings in SQL CHECK syntax, e.g. \"default_discount_pct <= max_discount_pct\": comparisons, IS [NOT] NULL, [NOT] IN, [NOT] BETWEEN, regex matches (~ ~* !~ !~*) against a string literal, AND/OR/NOT, + - * /, literals and setting codes (bare or \"quoted\"). No functions, casts or [field] brackets; IS NULL rather than = null. The settings it names are found in it: writing any of them re-checks the rule."
+				},
+				"message": {
+					"type": "string",
+					"description": "Violation message. Localizable via translations/<locale>.json under settings.$constraints.<name>.message."
+				}
+			}
+		},
 		"setting": {
 			"type": "object",
 			"properties": {

package/schemas/translations.schema.json

@@ -46,7 +46,19 @@
 		},
 		"settings": {
 			"type": "object",
-			"description": "Setting code (settings.json) → label and description.",
+			"description": "Setting code (settings.json) → label and description; $constraints → constraint name → message.",
+			"properties": {
+				"$constraints": {
+					"type": "object",
+					"additionalProperties": {
+						"type": "object",
+						"additionalProperties": false,
+						"properties": {
+							"message": { "type": "string" }
+						}
+					}
+				}
+			},
 			"additionalProperties": {
 				"$ref": "#/$defs/labelDesc"
 			}

package/src/dsl/builtins.ts

@@ -227,9 +227,9 @@ export const BUILTINS: Builtin[] = [
 
 	// Utilities
 	{ name: "now", signature: "now()", returns: "datetime", doc: "Current date/time. Lowercase — this is the execute-block date function." },
-	{ name: "addDays", signature: "addDays(date, n)", returns: "date", doc: "Add `n` days to a date." },
-	{ name: "addMinutes", signature: "addMinutes(date, n)", returns: "datetime", doc: "Add `n` minutes." },
-	{ name: "addSeconds", signature: "addSeconds(date, n)", returns: "datetime", doc: "Add `n` seconds." },
+	{ name: "addDays", signature: "addDays(date, n)", returns: "date | string", doc: "Add `n` days. Takes a date field, a `Date` or an ISO string; a date field stays a date and a `yyyy-MM-dd` string stays a string. Null stays null; any other value is an error." },
+	{ name: "addMinutes", signature: "addMinutes(date, n)", returns: "datetime", doc: "Add `n` minutes. Takes a date field, a `Date` or an ISO string; the result is a timestamp. Null stays null; any other value is an error." },
+	{ name: "addSeconds", signature: "addSeconds(date, n)", returns: "datetime", doc: "Add `n` seconds. Takes a date field, a `Date` or an ISO string; the result is a timestamp. Null stays null; any other value is an error." },
 	{ name: "currentUserId", signature: "currentUserId()", returns: "long", doc: "The acting user's tenant user ID." },
 	{ name: "flush", signature: "flush()", returns: "void", doc: "Flush pending writes so a following read sees them." },
 	{ name: "tryParseJson", signature: "tryParseJson(value)", returns: "any | null", doc: "Parse JSON, returning `null` on failure instead of throwing." },

package/src/index.ts

@@ -132,7 +132,8 @@ export type {
 	TranslatedReport,
 	TranslatedWithOptions,
 } from "./translations";
-export type { SettingsFile, SettingDef, SettingBaseDatatype } from "./settings";
+export { settingDefsOf } from "./settings";
+export type { SettingsFile, SettingDef, SettingConstraintDef, SettingBaseDatatype } from "./settings";
 export {
 	REGISTER_KINDS,
 	REGISTER_CODE,

package/src/settings.ts

@@ -38,5 +38,28 @@ export type SettingDef =
 		params?: never;
 	});
 
-/** A `settings.json` file: setting code → definition. */
-export type SettingsFile = Record<string, SettingDef>;
+/** A check across a module's settings: SQL over setting codes, as an entity check constraint. */
+export interface SettingConstraintDef {
+	type: "check";
+	/** PostgreSQL boolean over setting codes; writing any setting it names re-checks it. */
+	expression: string;
+	message?: string;
+}
+
+/**
+ * A `settings.json` file: setting code → definition, plus the optional `$constraints`. A
+ * setting code cannot start with `$`, but TypeScript cannot exclude it from the index, so
+ * the index admits the constraints map too.
+ */
+export type SettingsFile = {
+	$constraints?: Record<string, SettingConstraintDef>;
+	[settingCd: string]: SettingDef | Record<string, SettingConstraintDef> | undefined;
+};
+
+/** The settings of a file, without its `$constraints`. */
+export function settingDefsOf(file: SettingsFile): Record<string, SettingDef> {
+	const defs: Record<string, SettingDef> = {};
+	for (const [code, def] of Object.entries(file))
+		if (code !== "$constraints" && def) defs[code] = def as SettingDef;
+	return defs;
+}