@dforge-core/metadata 0.0.7 → 0.0.8

package/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to `@dforge-core/metadata` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.8] — 2026-07-17
+
+### Fixed
+
+- `deriveDbDatatype` now returns `jsonb` (not `bytea`) for the `file` and `image`
+  field types, matching the server's `DdlService.ResolveDbTypeFromFieldType`.
+  These types classify as `binary`, but dForge stores a JSON metadata reference
+  (`{ storagePath, fileName, … }`) — the bytes live in file storage. Previously
+  an omitted `dbDatatype` on a file/image column derived `bytea`, which broke
+  file attachments on save.
+
 ## [0.0.3] — 2026-06-14
 
 ### Added

package/dist/derive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"derive.d.ts","sourceRoot":"","sources":["../src/derive.ts"],"names":[],"mappings":"AASA,sEAAsE;AACtE,eAAO,MAAM,aAAa,KAAK,CAAC;AAKhC,MAAM,WAAW,aAAa;IAC7B,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM,GAAG,IAAI,CAuBhG;AAED,+EAA+E;AAC/E,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAItF;AAED,uFAAuF;AACvF,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE1E"}
+{"version":3,"file":"derive.d.ts","sourceRoot":"","sources":["../src/derive.ts"],"names":[],"mappings":"AASA,sEAAsE;AACtE,eAAO,MAAM,aAAa,KAAK,CAAC;AAkBhC,MAAM,WAAW,aAAa;IAC7B,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM,GAAG,IAAI,CA4BhG;AAED,+EAA+E;AAC/E,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAItF;AAED,uFAAuF;AACvF,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE1E"}

package/dist/derive.js

@@ -9,6 +9,18 @@ import { getFieldType } from "./field-types";
 export const NUMERIC_TOTAL = 18;
 /** Field types whose natural storage is unbounded `text` rather than `varchar`. */
 const TEXT_BACKED = new Set(["textarea", "richtext", "code"]);
+/**
+ * Field types the server pins to a fixed column type regardless of their base
+ * datatype — mirrors `DdlService.ResolveDbTypeFromFieldType`. `file`/`image`
+ * classify as `binary`, but dForge stores them as a JSON metadata reference
+ * (`{ storagePath, fileName, … }`), NOT inline `bytea`; the column is `jsonb`.
+ * Without this override the base path derives `bytea`, and the file-attach
+ * pipeline — which reads/writes that JSON — fails on save.
+ */
+const DB_DATATYPE_OVERRIDE = {
+    file: "jsonb",
+    image: "jsonb",
+};
 /**
  * Derive the PostgreSQL `dbDatatype` for a field type. Returns `null` for
  * field types backed by relationships/sets (lookup, grid) that have no physical
@@ -22,6 +34,11 @@ export function deriveDbDatatype(fieldTypeCd, options = {}) {
     // column — the FK lives on a separate hidden column.
     if (ft.columnType === "R" || ft.columnType === "S")
         return null;
+    // Server-pinned column types that don't follow the base-datatype path
+    // (file/image → jsonb, not bytea). Mirrors ResolveDbTypeFromFieldType.
+    const override = DB_DATATYPE_OVERRIDE[ft.cd];
+    if (override)
+        return override;
     const base = baseToDbDatatype(ft.baseDatatypeCd);
     if (base === null)
         return null; // other non-physical base (link/ref/set)

package/dist/derive.js.map

@@ -1 +1 @@
-{"version":3,"file":"derive.js","sourceRoot":"","sources":["../src/derive.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,yEAAyE;AACzE,EAAE;AACF,2EAA2E;AAC3E,+EAA+E;AAE/E,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,sEAAsE;AACtE,MAAM,CAAC,MAAM,aAAa,GAAG,EAAE,CAAC;AAEhC,mFAAmF;AACnF,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,CAAC,UAAU,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;AAS9D;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,WAAmB,EAAE,UAAyB,EAAE;IAChF,MAAM,EAAE,GAAG,YAAY,CAAC,WAAW,CAAC,CAAC;IACrC,IAAI,CAAC,EAAE;QAAE,OAAO,SAAS,CAAC;IAE1B,wEAAwE;IACxE,qDAAqD;IACrD,IAAI,EAAE,CAAC,UAAU,KAAK,GAAG,IAAI,EAAE,CAAC,UAAU,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IAEhE,MAAM,IAAI,GAAG,gBAAgB,CAAC,EAAE,CAAC,cAAc,CAAC,CAAC;IACjD,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC,CAAC,yCAAyC;IAEzE,IAAI,EAAE,CAAC,cAAc,KAAK,QAAQ,EAAE,CAAC;QACpC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC,SAAS,CAAC;QACpD,OAAO,SAAS,IAAI,IAAI,CAAC,CAAC,CAAC,WAAW,aAAa,IAAI,SAAS,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IACjF,CAAC;IAED,IAAI,EAAE,CAAC,cAAc,KAAK,QAAQ,EAAE,CAAC;QACpC,IAAI,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YAAE,OAAO,MAAM,CAAC;QAC1C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,MAAM,CAAC;QAC3C,OAAO,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,WAAW,MAAM,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IAC1D,CAAC;IAED,OAAO,IAAI,CAAC;AACb,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,aAAa,CAAC,WAAmB;IAChD,MAAM,EAAE,GAAG,YAAY,CAAC,WAAW,CAAC,CAAC;IACrC,IAAI,CAAC,EAAE,EAAE,SAAS;QAAE,OAAO,SAAS,CAAC;IACrC,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,EAAE,CAAC;AAC5B,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,kBAAkB,CAAC,WAAmB;IACrD,OAAO,YAAY,CAAC,WAAW,CAAC,EAAE,cAAc,CAAC;AAClD,CAAC"}
+{"version":3,"file":"derive.js","sourceRoot":"","sources":["../src/derive.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,yEAAyE;AACzE,EAAE;AACF,2EAA2E;AAC3E,+EAA+E;AAE/E,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,sEAAsE;AACtE,MAAM,CAAC,MAAM,aAAa,GAAG,EAAE,CAAC;AAEhC,mFAAmF;AACnF,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,CAAC,UAAU,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;AAE9D;;;;;;;GAOG;AACH,MAAM,oBAAoB,GAA2B;IACpD,IAAI,EAAE,OAAO;IACb,KAAK,EAAE,OAAO;CACd,CAAC;AASF;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,WAAmB,EAAE,UAAyB,EAAE;IAChF,MAAM,EAAE,GAAG,YAAY,CAAC,WAAW,CAAC,CAAC;IACrC,IAAI,CAAC,EAAE;QAAE,OAAO,SAAS,CAAC;IAE1B,wEAAwE;IACxE,qDAAqD;IACrD,IAAI,EAAE,CAAC,UAAU,KAAK,GAAG,IAAI,EAAE,CAAC,UAAU,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IAEhE,sEAAsE;IACtE,uEAAuE;IACvE,MAAM,QAAQ,GAAG,oBAAoB,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAC7C,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAE9B,MAAM,IAAI,GAAG,gBAAgB,CAAC,EAAE,CAAC,cAAc,CAAC,CAAC;IACjD,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC,CAAC,yCAAyC;IAEzE,IAAI,EAAE,CAAC,cAAc,KAAK,QAAQ,EAAE,CAAC;QACpC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC,SAAS,CAAC;QACpD,OAAO,SAAS,IAAI,IAAI,CAAC,CAAC,CAAC,WAAW,aAAa,IAAI,SAAS,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IACjF,CAAC;IAED,IAAI,EAAE,CAAC,cAAc,KAAK,QAAQ,EAAE,CAAC;QACpC,IAAI,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YAAE,OAAO,MAAM,CAAC;QAC1C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,MAAM,CAAC;QAC3C,OAAO,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,WAAW,MAAM,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IAC1D,CAAC;IAED,OAAO,IAAI,CAAC;AACb,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,aAAa,CAAC,WAAmB;IAChD,MAAM,EAAE,GAAG,YAAY,CAAC,WAAW,CAAC,CAAC;IACrC,IAAI,CAAC,EAAE,EAAE,SAAS;QAAE,OAAO,SAAS,CAAC;IACrC,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,EAAE,CAAC;AAC5B,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,kBAAkB,CAAC,WAAmB;IACrD,OAAO,YAAY,CAAC,WAAW,CAAC,EAAE,cAAc,CAAC;AAClD,CAAC"}

package/dist/triggers.d.ts

@@ -14,7 +14,11 @@ export interface TriggerDef {
     action: string;
     /** Static parameters passed to the action, merged with the injected record id. */
     params?: Record<string, unknown>;
-    /** Run the action in the background after the triggering tx commits (default false). */
+    /**
+     * true: run in the background after the triggering tx commits (failures logged, not surfaced).
+     * false (default): run synchronously in the same tx — a failure rolls the mutation back and
+     * returns the error to the caller. Keep async:false actions fast.
+     */
     async?: boolean;
 }
 /** A `logic/triggers.json` file. */

package/dist/triggers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"triggers.d.ts","sourceRoot":"","sources":["../src/triggers.ts"],"names":[],"mappings":"AAEA,6CAA6C;AAC7C,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,eAAe,GAAG,KAAK,CAAC;AAEnF,oCAAoC;AACpC,MAAM,WAAW,UAAU;IAC1B,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,WAAW,CAAC;IACnB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,wFAAwF;IACxF,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,oCAAoC;AACpC,MAAM,WAAW,YAAY;IAC5B,QAAQ,EAAE,UAAU,EAAE,CAAC;CACvB"}
+{"version":3,"file":"triggers.d.ts","sourceRoot":"","sources":["../src/triggers.ts"],"names":[],"mappings":"AAEA,6CAA6C;AAC7C,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,eAAe,GAAG,KAAK,CAAC;AAEnF,oCAAoC;AACpC,MAAM,WAAW,UAAU;IAC1B,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,WAAW,CAAC;IACnB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,oCAAoC;AACpC,MAAM,WAAW,YAAY;IAC5B,QAAQ,EAAE,UAAU,EAAE,CAAC;CACvB"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dforge-core/metadata",
-	"version": "0.0.7",
+	"version": "0.0.8",
 	"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",

package/schemas/triggers.schema.json

@@ -50,7 +50,7 @@
 				"async": {
 					"type": "boolean",
 					"default": false,
-					"description": "When true, the action runs in the background — the triggering transaction commits before the action starts. Recommended for slow actions (emails, external API calls). When false, the action runs in the same transaction; failures roll back the original DB change."
+					"description": "When true, the action runs in the background — the triggering transaction commits before the action starts. Recommended for slow actions (emails, external API calls); background failures are logged, not surfaced to the caller. When false, the action runs synchronously inside the same transaction as the triggering insert/update/delete: if the action fails (e.g. calls error()), the whole mutation rolls back and the error is returned to the caller. Keep async:false actions fast — they run on the request's transaction."
 				}
 			},
 			"additionalProperties": false

package/src/derive.ts

@@ -13,6 +13,19 @@ export const NUMERIC_TOTAL = 18;
 /** Field types whose natural storage is unbounded `text` rather than `varchar`. */
 const TEXT_BACKED = new Set(["textarea", "richtext", "code"]);
 
+/**
+ * Field types the server pins to a fixed column type regardless of their base
+ * datatype — mirrors `DdlService.ResolveDbTypeFromFieldType`. `file`/`image`
+ * classify as `binary`, but dForge stores them as a JSON metadata reference
+ * (`{ storagePath, fileName, … }`), NOT inline `bytea`; the column is `jsonb`.
+ * Without this override the base path derives `bytea`, and the file-attach
+ * pipeline — which reads/writes that JSON — fails on save.
+ */
+const DB_DATATYPE_OVERRIDE: Record<string, string> = {
+	file: "jsonb",
+	image: "jsonb",
+};
+
 export interface DeriveOptions {
 	/** Author-specified max length; overrides the field type's default. */
 	maxLen?: number | null;
@@ -33,6 +46,11 @@ export function deriveDbDatatype(fieldTypeCd: string, options: DeriveOptions = {
 	// column — the FK lives on a separate hidden column.
 	if (ft.columnType === "R" || ft.columnType === "S") return null;
 
+	// Server-pinned column types that don't follow the base-datatype path
+	// (file/image → jsonb, not bytea). Mirrors ResolveDbTypeFromFieldType.
+	const override = DB_DATATYPE_OVERRIDE[ft.cd];
+	if (override) return override;
+
 	const base = baseToDbDatatype(ft.baseDatatypeCd);
 	if (base === null) return null; // other non-physical base (link/ref/set)
 

package/src/triggers.ts

@@ -17,7 +17,11 @@ export interface TriggerDef {
 	action: string;
 	/** Static parameters passed to the action, merged with the injected record id. */
 	params?: Record<string, unknown>;
-	/** Run the action in the background after the triggering tx commits (default false). */
+	/**
+	 * true: run in the background after the triggering tx commits (failures logged, not surfaced).
+	 * false (default): run synchronously in the same tx — a failure rolls the mutation back and
+	 * returns the error to the caller. Keep async:false actions fast.
+	 */
 	async?: boolean;
 }