@memberjunction/core 6.1.0-edge.1 → 6.1.0-edge.3

package/dist/index.js

@@ -15,6 +15,7 @@ export * from "./generic/entityTransactionScope.js";
 export * from "./generic/entityCompanion.js";
 export * from "./generic/entitySavePlan.js";
 export * from "./generic/relatedRecordCollection.js";
+export * from "./generic/embeddedRecord.js";
 export * from "./generic/relatedRecordBatchLoader.js";
 export * from "./generic/saveEntityGraphOperation.js";
 export * from "./generic/BaseEntitySaveQueue.js";
@@ -24,6 +25,7 @@ export * from "./generic/providerBase.js";
 export * from "./generic/baseRemotableOperation.js";
 export * from "./generic/remoteOperationDispatch.js";
 export * from "./generic/entityInfo.js";
+export * from "./generic/entityConfiguration.js";
 export * from "./generic/externalDataSourceTypes.js";
 export * from "./generic/externalDataSourceReadRouter.js";
 export * from "./generic/securityInfo.js";
@@ -57,6 +59,7 @@ export * from "./generic/column-descriptors.js";
 export * from "./generic/data-table.js";
 export * from "./generic/data-snapshot.js";
 export * from "./generic/permissionInterfaces.js";
+export * from "./generic/JSONType-interfaces/IFileStorageProviderConfiguration.js";
 export function SetProvider(provider) {
     Metadata.Provider = provider; // global-provider-ok: this IS the global provider setter
     BaseEntity.Provider = provider;

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE1C,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sBAAsB,CAAC;AACrC,cAAc,wCAAwC,CAAC;AACvD,cAAc,sBAAsB,CAAC;AACrC,cAAc,kCAAkC,CAAC;AACjD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,mCAAmC,CAAC;AAClD,cAAc,oCAAoC,CAAC;AACnD,cAAc,oCAAoC,CAAC;AACnD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,kCAAkC,CAAC;AACjD,cAAc,mCAAmC,CAAC;AAClD,cAAc,sBAAsB,CAAC;AACrC,cAAc,mCAAmC,CAAC;AAClD,cAAc,wCAAwC,CAAC;AACvD,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4CAA4C,CAAC;AAC3D,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AAErC,cAAc,kCAAkC,CAAC;AACjD,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAE3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wCAAwC,CAAC;AACvD,cAAc,qBAAqB,CAAC;AACpC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gCAAgC,CAAC;AAE/C,MAAM,UAAU,WAAW,CAAC,QAAQ;IAChC,QAAQ,CAAC,QAAQ,GAAG,QAAQ,CAAC,CAAC,yDAAyD;IACvF,UAAU,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC/B,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC5B,QAAQ,CAAC,QAAQ,GAAG,QAAQ,CAAC;AACjC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE1C,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sBAAsB,CAAC;AACrC,cAAc,wCAAwC,CAAC;AACvD,cAAc,sBAAsB,CAAC;AACrC,cAAc,kCAAkC,CAAC;AACjD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,mCAAmC,CAAC;AAClD,cAAc,0BAA0B,CAAC;AACzC,cAAc,oCAAoC,CAAC;AACnD,cAAc,oCAAoC,CAAC;AACnD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,kCAAkC,CAAC;AACjD,cAAc,mCAAmC,CAAC;AAClD,cAAc,sBAAsB,CAAC;AACrC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,mCAAmC,CAAC;AAClD,cAAc,wCAAwC,CAAC;AACvD,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4CAA4C,CAAC;AAC3D,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AAErC,cAAc,kCAAkC,CAAC;AACjD,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAE3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wCAAwC,CAAC;AACvD,cAAc,qBAAqB,CAAC;AACpC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,iEAAiE,CAAC;AAEhF,MAAM,UAAU,WAAW,CAAC,QAAQ;IAChC,QAAQ,CAAC,QAAQ,GAAG,QAAQ,CAAC,CAAC,yDAAyD;IACvF,UAAU,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC/B,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC5B,QAAQ,CAAC,QAAQ,GAAG,QAAQ,CAAC;AACjC,CAAC"}

package/dist/views/runView.d.ts

@@ -112,6 +112,16 @@ export declare class RunViewParams {
      * Dynamic Views in combination with the optional ExtraFilter
      */
     EntityName?: string;
+    /**
+     * optional - choose the live source-of-truth vs the materialized snapshot, for entities that have a
+     * base-view materialization (an `MJ: Materialized Results` row with `SourceType='EntityBaseView'`).
+     * Defaults to `'Live'`. When `'Materialized'`, the read is routed to the materialized wrapper view
+     * (`materialized_vw<Name>`) instead of the entity's live base view — RLS, paging, and field selection
+     * apply identically because it's the same entity/shape. Choosing the snapshot is an explicit caller
+     * decision (never silent). No effect on entities that have no base-view materialization (the wrapper
+     * view won't exist). The enum (vs. a bare boolean) leaves room for future modes without a breaking change.
+     */
+    DataSource?: 'Live' | 'Materialized';
     /**
      * An optional SQL WHERE clause that you can add to the existing filters on a stored view. For dynamic views, you can either
      * run a view without a filter (if the entity definition allows it with AllowAllRowsAPI=1) or filter with any valid SQL WHERE clause.
@@ -247,6 +257,41 @@ export declare class RunViewParams {
      * Result Type is: 'simple', 'entity_object', or 'count_only' and defaults to 'simple'. If 'entity_object' is specified, the Results[] array will contain
      * BaseEntity-derived objects instead of simple objects. This is useful if you want to work with the data in a more strongly typed manner and/or
      * if you plan to do any update/delete operations on the data after it is returned. The 'count_only' option will return no rows, but the TotalRowCount property of the RunViewResult object will be populated.
+     *
+     * ## What `'simple'` rows actually contain — and what `T` does and does not check
+     *
+     * `'simple'` returns plain row objects, but the pipeline normalizes their VALUES to the shapes
+     * the generated entity types declare, identically on every tier: `Date` columns hold real
+     * `Date`s and numeric columns hold `number`s, whether the call ran server-side against the
+     * database or in a browser over GraphQL, and whether it was a fresh query or a cache hit.
+     * (`NULL` stays `NULL`, an unparseable value is left as-is rather than becoming `Invalid
+     * Date`, and integer strings beyond `Number.MAX_SAFE_INTEGER` stay strings to preserve
+     * BIGINT precision.)
+     *
+     * `RunView<T>` still takes a **caller-supplied** `T` the compiler does not verify, so know
+     * what a plain row can and cannot honor when you pass a generated entity type:
+     *
+     * ```typescript
+     * // Date and numeric fields are truthful on simple rows:
+     * const rows = await rv.RunView<OrderEntity>({ EntityName: 'Orders', ResultType: 'simple' });
+     * rows.Results[0].OrderDate.getFullYear();   // works — a real Date on every tier
+     *
+     * // But a plain row is still not an entity:
+     * rows.Results[0].Save();                    // compiles, crashes — no entity methods
+     * // ...and a closed-union column (e.g. Status) holds whatever string the database held.
+     * ```
+     *
+     * Two caveats worth knowing:
+     * - **`Fields` narrowing**: if you narrowed the query with `Fields`, non-selected properties
+     *   simply don't exist on the rows, whatever `T` claims.
+     * - **View-only runs**: a call that passes only `ViewID`/`ViewName` (no `EntityName` and no
+     *   loaded `ViewEntity`) skips normalization, since the entity is not synchronously
+     *   resolvable that deep in the pipeline. Pass `EntityName` alongside the view identifier to
+     *   get normalized rows.
+     *
+     * Rule of thumb: **want entity behavior — methods, validation, save, related records — ask
+     * for entity objects.** Choose `'simple'` for cheap read-only rows; its dates and numbers
+     * are already the types your entity declares.
      */
     ResultType?: 'simple' | 'entity_object' | 'count_only';
     /**
@@ -413,6 +458,19 @@ export declare class RunViewParams {
      */
     private static platformSQLEqual;
 }
+/**
+ * Canonical test for whether a `RunViewParams.DataSource` value requests the MATERIALIZED snapshot.
+ *
+ * `DataSource` is typed `'Live' | 'Materialized'` here, but it crosses a GraphQL `String` boundary
+ * (RunViewResolver declares it as an unconstrained `@Field(() => String)`), so a cross-version or non-MJ
+ * client can send `'materialized'`, `'MATERIALIZED'`, or `'Materialized '`. This trims + lowercases before
+ * comparing, so every such variant is recognized as materialized; anything else (including a typo) means a
+ * live read — the safe default. Use this at EVERY DataSource decision point (read routing in
+ * GetEffectiveBaseView, the cache-eligibility gate in runViewCacheEligible, and the cache fingerprint in
+ * LocalCacheManager) so a mis-cased request can never be routed to the snapshot by one site while being
+ * cached as Live by another (the silent-stale hazard that separate `=== 'Materialized'` checks allow).
+ */
+export declare function IsMaterializedDataSource(dataSource: string | null | undefined): boolean;
 /**
  * Class for running views in a generic, tier-independent manner - uses a provider model for
  * implementation transparently from the viewpoint of the consumer of the class. By default the RunView class you create will

package/dist/views/runView.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runView.d.ts","sourceRoot":"","sources":["../../src/views/runView.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runView.d.ts","sourceRoot":"","sources":["../../src/views/runView.ts"],"names":[],"mappings":"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"}

package/dist/views/runView.js

@@ -112,6 +112,11 @@ export class RunViewParams {
             return false;
         if (a.CacheLocalTTL !== b.CacheLocalTTL)
             return false;
+        // A Live↔Materialized DataSource toggle changes the result set and MUST trigger a reload. Compared via
+        // IsMaterializedDataSource so undefined/'Live' are treated as equal (no spurious reload) while a switch to
+        // (or from) 'Materialized' is not — matching the read-routing decision everywhere else.
+        if (IsMaterializedDataSource(a.DataSource) !== IsMaterializedDataSource(b.DataSource))
+            return false;
         // Compare ViewEntity by reference (deep comparison would be expensive)
         if (a.ViewEntity !== b.ViewEntity)
             return false;
@@ -195,6 +200,21 @@ export class RunViewParams {
             && a.postgresql === b.postgresql;
     }
 }
+/**
+ * Canonical test for whether a `RunViewParams.DataSource` value requests the MATERIALIZED snapshot.
+ *
+ * `DataSource` is typed `'Live' | 'Materialized'` here, but it crosses a GraphQL `String` boundary
+ * (RunViewResolver declares it as an unconstrained `@Field(() => String)`), so a cross-version or non-MJ
+ * client can send `'materialized'`, `'MATERIALIZED'`, or `'Materialized '`. This trims + lowercases before
+ * comparing, so every such variant is recognized as materialized; anything else (including a typo) means a
+ * live read — the safe default. Use this at EVERY DataSource decision point (read routing in
+ * GetEffectiveBaseView, the cache-eligibility gate in runViewCacheEligible, and the cache fingerprint in
+ * LocalCacheManager) so a mis-cased request can never be routed to the snapshot by one site while being
+ * cached as Live by another (the silent-stale hazard that separate `=== 'Materialized'` checks allow).
+ */
+export function IsMaterializedDataSource(dataSource) {
+    return typeof dataSource === 'string' && dataSource.trim().toLowerCase() === 'materialized';
+}
 /**
  * Class for running views in a generic, tier-independent manner - uses a provider model for
  * implementation transparently from the viewpoint of the consumer of the class. By default the RunView class you create will

package/dist/views/runView.js.map

@@ -1 +1 @@
-{"version":3,"file":"runView.js","sourceRoot":"","sources":["../../src/views/runView.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runView.js","sourceRoot":"","sources":["../../src/views/runView.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAc,MAAM,wBAAwB,CAAC;AAmB9D;;;;;;;;;GASG;AACH,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IAChD,YACoB,UAAkB,EAClB,MAAkC,EAClD,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,eAAU,GAAV,UAAU,CAAQ;QAClB,WAAM,GAAN,MAAM,CAA4B;QAIlD,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;IAC5C,CAAC;CACJ;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,oCAAoC,GAA0B;IACvE,kBAAkB;IAClB,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS;IACtC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,YAAY;IAC3C,OAAO,EAAE,MAAM,EAAE,kBAAkB;IACnC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO;IACvD,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM;IAC1E,KAAK;IACL,iFAAiF;IACjF,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,mBAAmB,EAAE,WAAW,EAAE,WAAW,EAAE,0BAA0B,EAAE,6BAA6B,EAAE,SAAS;CAC3K,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,+BAA+B,CAAC,WAAsC;IAClF,IAAI,CAAC,WAAW;QAAE,OAAO,KAAK,CAAC;IAC/B,kEAAkE;IAClE,MAAM,UAAU,GAAG,WAAW,CAAC,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACpF,OAAO,oCAAoC,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;AACrE,CAAC;AA4CD;;;;;;;;GAQG;AACH,MAAM,OAAO,aAAa;IAgWtB;;;;;;;OAOG;IACI,MAAM,CAAC,MAAM,CAAC,CAAmC,EAAE,CAAmC;QACzF,8BAA8B;QAC9B,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC,CAAC,wCAAwC;QAClE,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC,CAAC,yCAAyC;QAErE,kDAAkD;QAClD,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC;QACxC,IAAI,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,QAAQ;YAAE,OAAO,KAAK,CAAC;QAC5C,IAAI,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,UAAU;YAAE,OAAO,KAAK,CAAC;QAChD,IAAI,CAAC,aAAa,CAAC,gBAAgB,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,WAAW,CAAC;YAAE,OAAO,KAAK,CAAC;QAChF,IAAI,CAAC,aAAa,CAAC,gBAAgB,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC;YAAE,OAAO,KAAK,CAAC;QACxE,IAAI,CAAC,CAAC,gBAAgB,KAAK,CAAC,CAAC,gBAAgB;YAAE,OAAO,KAAK,CAAC;QAC5D,IAAI,CAAC,CAAC,oBAAoB,KAAK,CAAC,CAAC,oBAAoB;YAAE,OAAO,KAAK,CAAC;QACpE,IAAI,CAAC,CAAC,+BAA+B,KAAK,CAAC,CAAC,+BAA+B;YAAE,OAAO,KAAK,CAAC;QAC1F,IAAI,CAAC,CAAC,qBAAqB,KAAK,CAAC,CAAC,qBAAqB;YAAE,OAAO,KAAK,CAAC;QACtE,IAAI,CAAC,CAAC,eAAe,KAAK,CAAC,CAAC,eAAe;YAAE,OAAO,KAAK,CAAC;QAC1D,IAAI,CAAC,CAAC,aAAa,KAAK,CAAC,CAAC,aAAa;YAAE,OAAO,KAAK,CAAC;QACtD,IAAI,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC;QAC1C,IAAI,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,QAAQ;YAAE,OAAO,KAAK,CAAC;QAC5C,IAAI,CAAC,aAAa,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC;YAAE,OAAO,KAAK,CAAC;QACvE,IAAI,CAAC,CAAC,aAAa,KAAK,CAAC,CAAC,aAAa;YAAE,OAAO,KAAK,CAAC;QACtD,IAAI,CAAC,CAAC,mBAAmB,KAAK,CAAC,CAAC,mBAAmB;YAAE,OAAO,KAAK,CAAC;QAClE,IAAI,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,UAAU;YAAE,OAAO,KAAK,CAAC;QAChD,IAAI,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,UAAU;YAAE,OAAO,KAAK,CAAC;QAChD,IAAI,CAAC,CAAC,aAAa,KAAK,CAAC,CAAC,aAAa;YAAE,OAAO,KAAK,CAAC;QACtD,uGAAuG;QACvG,2GAA2G;QAC3G,wFAAwF;QACxF,IAAI,wBAAwB,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,wBAAwB,CAAC,CAAC,CAAC,UAAU,CAAC;YAAE,OAAO,KAAK,CAAC;QAEpG,uEAAuE;QACvE,IAAI,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,UAAU;YAAE,OAAO,KAAK,CAAC;QAEhD,uBAAuB;QACvB,IAAI,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;YAAE,OAAO,KAAK,CAAC;QAEjE,2BAA2B;QAC3B,IAAI,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,UAAU,CAAC;YAAE,OAAO,KAAK,CAAC;QAE7E,OAAO,IAAI,CAAC;IAChB,CAAC;IAED;;OAEG;IACK,MAAM,CAAC,WAAW,CAAC,CAAuB,EAAE,CAAuB;QACvE,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC,CAAC,mCAAmC;QAC7D,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC,CAAC,oCAAoC;QAChE,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC;QACxC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAChC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;gBAAE,OAAO,KAAK,CAAC;QACpC,CAAC;QACD,OAAO,IAAI,CAAC;IAChB,CAAC;IAED;;;OAGG;IACK,MAAM,CAAC,aAAa,CAAC,CAA2B,EAAE,CAA2B;QACjF,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACzB,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;QAC3B,MAAM,MAAM,GAAG,CAAC,CAAC,aAAa,IAAI,EAAE,CAAC;QACrC,MAAM,MAAM,GAAG,CAAC,CAAC,aAAa,IAAI,EAAE,CAAC;QACrC,IAAI,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC;QAClD,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;YACxB,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,IAAI,CAAC,SAAS,CAAC,CAAC;YAC/D,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK;gBAAE,OAAO,KAAK,CAAC;QAC3D,CAAC;QACD,OAAO,IAAI,CAAC;IAChB,CAAC;IAED;;OAEG;IACK,MAAM,CAAC,eAAe,CAAC,CAAoC,EAAE,CAAoC;QACrG,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC,CAAC,mCAAmC;QAC7D,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC,CAAC,oCAAoC;QAChE,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC;QACxC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAChC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU;gBAAE,OAAO,KAAK,CAAC;YACtD,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK;gBAAE,OAAO,KAAK,CAAC;QAChD,CAAC;QACD,OAAO,IAAI,CAAC;IAChB,CAAC;IAED;;;OAGG;IACK,MAAM,CAAC,gBAAgB,CAAC,CAAmC,EAAE,CAAmC;QACpG,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC,CAAC,oDAAoD;QAC9E,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI;YAAE,OAAO,KAAK,CAAC;QACzC,6EAA6E;QAC7E,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QACjE,+BAA+B;QAC/B,OAAO,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO;eACvB,CAAC,CAAC,SAAS,KAAK,CAAC,CAAC,SAAS;eAC3B,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,UAAU,CAAC;IACzC,CAAC;CACJ;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,wBAAwB,CAAC,UAAqC;IAC1E,OAAO,OAAO,UAAU,KAAK,QAAQ,IAAI,UAAU,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,cAAc,CAAC;AAChG,CAAC;AAED;;;;;GAKG;AACH,MAAM,OAAO,OAAO;IAEhB;;;OAGG;IACH,YAAY,WAAoC,IAAI;QAL5C,cAAS,GAA4B,IAAI,CAAC;QAM9C,IAAI,QAAQ;YACR,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;IAClC,CAAC;IAED;;;;;;;OAOG;IACI,MAAM,CAAC,oBAAoB,CAAC,QAA2B;QAC1D,OAAO,IAAI,OAAO,CAAC,QAAuC,CAAC,CAAC;IAChE,CAAC;IAED;;OAEG;IACH,IAAW,aAAa;QACpB,OAAO,IAAI,CAAC,SAAS,IAAI,OAAO,CAAC,QAAQ,CAAC;IAC9C,CAAC;IAGD;;;;;OAKG;IACI,KAAK,CAAC,OAAO,CAAU,MAAqB,EAAE,WAAsB;QACvE,mHAAmH;QACnH,OAAO,IAAI,CAAC,aAAa,CAAC,OAAO,CAAI,MAAM,EAAE,WAAW,CAAC,CAAC;IAC9D,CAAC;IAED;;;;;OAKG;IACI,KAAK,CAAC,QAAQ,CAAU,MAAuB,EAAE,WAAsB;QAC1E,gEAAgE;QAChE,0DAA0D;QAC1D,OAAO,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC5D,CAAC;aAEc,uBAAkB,GAAW,oBAAoB,AAA/B,CAAgC;IACjE;;;OAGG;IACI,MAAM,KAAK,QAAQ;QACtB,MAAM,CAAC,GAAG,QAAQ,CAAC,QAAQ,CAAC,oBAAoB,EAAE,CAAC;QACnD,IAAI,CAAC;YACD,OAAO,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;;YAErC,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;IACtF,CAAC;IACM,MAAM,KAAK,QAAQ,CAAC,KAAuB;QAC9C,MAAM,CAAC,GAAG,QAAQ,CAAC,QAAQ,CAAC,oBAAoB,EAAE,CAAC;QACnD,IAAI,CAAC;YACD,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAAC,GAAG,KAAK,CAAC;;YAEtC,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;IACtF,CAAC;IAGD;;;;OAIG;IACI,MAAM,CAAC,KAAK,CAAC,8BAA8B,CAAC,MAAqB,EAAE,WAAqC,IAAI,EAAE,WAAsB;QACvI,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAyB,OAAO,CAAC,QAAQ,CAAC;QAEzE,IAAI,MAAM,CAAC,UAAU;YACjB,OAAO,MAAM,CAAC,UAAU,CAAC;aACxB,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;YACzB,MAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,kJAAkJ;YACtM,MAAM,MAAM,GAAG,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;YACtC,IAAI,MAAM;gBACN,OAAO,MAAM,CAAC,IAAI,CAAA;QAC1B,CAAC;aACI,IAAI,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YACxC,yDAAyD;YACzD,EAAE;YACF,+BAA+B;YAC/B,sFAAsF;YACtF,mFAAmF;YACnF,mFAAmF;YACnF,+EAA+E;YAC/E,oEAAoE;YACpE,iFAAiF;YACjF,oFAAoF;YACpF,kFAAkF;YAClF,gCAAgC;YAChC,MAAM,EAAE,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC;YAC3C,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC;gBAC5B,UAAU,EAAE,gBAAgB;gBAC5B,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,WAAW,MAAM,CAAC,QAAQ,GAAG;gBACtF,UAAU,EAAE,eAAe;aAC9B,EAAE,WAAW,CAAC,CAAC;YAChB,IAAI,MAAM,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACxD,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,uDAAuD;YAC5F,CAAC;YACD,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,aAAa,MAAM,CAAC,QAAQ,GAAG,CAAC;YAC9F,MAAM,IAAI,KAAK,CACX,YAAY,OAAO,0EAA0E;gBAC7F,GAAG,WAAW,CAAC,CAAC,CAAC,YAAY,WAAW,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,4DAA4D,IAAI;gBACpH,sEAAsE,CACzE,CAAC;QACN,CAAC;;YAEG,OAAO,IAAI,CAAC;IACpB,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@memberjunction/core",
   "type": "module",
-  "version": "6.1.0-edge.1",
+  "version": "6.1.0-edge.3",
   "description": "MemberJunction: Core Library including Metadata, Application, Entity Retrieval and Manipulation, and Utilities",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,7 +9,7 @@
     "/dist"
   ],
   "author": "MemberJunction.com",
-  "license": "ISC",
+  "license": "BUSL-1.1",
   "devDependencies": {
     "ts-node-dev": "^2.0.0",
     "typescript": "^5.9.3",
@@ -17,8 +17,8 @@
     "vitest": "^3.1.1"
   },
   "dependencies": {
-    "@memberjunction/global": "6.1.0-edge.1",
-    "@memberjunction/sql-dialect": "6.1.0-edge.1",
+    "@memberjunction/global": "6.1.0-edge.3",
+    "@memberjunction/sql-dialect": "6.1.0-edge.3",
     "rxjs": "^7.8.2",
     "zod": "^3.25.0",
     "debug": "^4.4.3"
@@ -28,6 +28,7 @@
     "url": "https://github.com/MemberJunction/MJ"
   },
   "scripts": {
+    "prebuild": "node scripts/sync-json-types.mjs",
     "start": "ts-node-dev src/index.ts",
     "build": "tsc && tsc-alias -f",
     "test": "vitest run",

package/readme.md

@@ -134,6 +134,7 @@ flowchart LR
 | `entityTransactionScope.ts` | `EntityTransactionScope` + `RunInEntityTransaction()` — the one provider-arbitrated transaction primitive, shared by IS-A, composites and application cascades |
 | `entityCompanion.ts` | `EntityCompanion` — named, serialisable state attached to a record (the "bag") |
 | `relatedRecordCollection.ts` | `RelatedRecordCollection<T>` — the typed parent/children companion |
+| `embeddedRecord.ts` | `EmbeddedRecord<T>` — owner-held 1:1 peer (`Deal.OrderID` → Order), inverted save order |
 | `relatedRecordBatchLoader.ts` | One batched child query per collection across a whole result set (`RunView.IncludeRelatedRecords`) |
 | `entitySavePlan.ts` | `EntitySavePlan` + executor — the ordered unit of work a composite save produces |
 | `saveEntityGraphOperation.ts` | `MJ.SaveEntityGraph` — routes a whole composite save to the server from a client provider |
@@ -359,6 +360,24 @@ const data = { ...entity };
 const data = { ...entity.GetAll(), customField: 'value' };
 ```
 
+#### Recursive Foreign Keys & Hierarchy Traversal
+
+When an entity has a single-column primary key and a self-referencing foreign key configured as a hierarchy (`EntityField.Configuration` setting `{ "Hierarchy": { "IsHierarchy": true } }`), CodeGen automatically adds strongly-typed hierarchy traversal helper methods to the generated subclass in `@memberjunction/core-entities`:
+
+```typescript
+// Fetch all descendants in the subtree with an optional maxDepth limit
+const descendants = await category.GetDescendants();     // all descendants
+const directAndGrand = await category.GetDescendants(2); // max 2 levels down
+
+// Fetch all ancestors from root down to this record's parent
+const ancestors = await category.GetAncestors();
+
+// Fetch direct child records
+const children = await category.GetChildren();
+```
+
+All three methods execute a single optimized `RunView` query using the view's computed `Root<Field>`, `<Field>Depth`, `<Field>Path`, and `<Field>IsLeaf` columns. See the [Recursive Foreign Keys & Hierarchy Traversal Guide](../../guides/RECURSIVE_FOREIGN_KEYS_AND_HIERARCHIES_GUIDE.md).
+
 #### State Tracking and Events
 
 BaseEntity provides comprehensive state tracking and lifecycle events.
@@ -565,6 +584,50 @@ if (typedResult.Success) {
 }
 ```
 
+#### `ResultType`: what `'simple'` rows contain, and what `T` does not check
+
+`ResultType` defaults to `'simple'`. Simple rows are plain objects, but their VALUES are
+normalized to the shapes the generated entity types declare — identically on every tier. A `Date`
+column holds a real `Date` and a numeric column holds a `number`, whether the call ran server-side
+against the database or in a browser over GraphQL, and whether it was a fresh query or a cache
+hit. (`NULL` stays `NULL`, unparseable values are left as-is rather than becoming `Invalid Date`,
+and integer strings beyond `Number.MAX_SAFE_INTEGER` stay strings to preserve BIGINT precision.)
+
+| | `'simple'` (default) | `'entity_object'` |
+|---|---|---|
+| What you get | plain objects, values normalized to the entity's field types | `BaseEntity`-derived instances |
+| A `DATETIME` column | a real `Date`, on every tier | a real `Date` (`BaseEntity` converts on `Get`/`Set`) |
+| Entity methods / validation | no | yes |
+| Save / delete the row | no | yes |
+| `IncludeRelatedRecords` | not available | yes |
+| `Fields` narrowing | yes — use it | ignored (entities need all fields) |
+| Cost | one plain object per row | field hydration per row |
+
+`RunView<T>` takes a **caller-supplied** `T` the compiler does not verify against `ResultType`,
+so know what a plain row can and cannot honor when you pass a generated entity type:
+
+```typescript
+// Date and numeric fields are truthful on simple rows:
+const rows = await rv.RunView<UserEntity>({ EntityName: 'Users', ResultType: 'simple' });
+rows.Results[0].CreatedAt.getFullYear();   // works — a real Date on every tier
+
+// But a plain row is still not an entity:
+rows.Results[0].Save();                    // compiles, crashes — no entity methods
+// ...and a closed-union column (e.g. Status) holds whatever string the database held.
+
+// When you need entity behavior, ask for entities:
+const users = await rv.RunView<UserEntity>({ EntityName: 'Users', ResultType: 'entity_object' });
+```
+
+Two caveats: with `Fields` narrowing, non-selected properties simply don't exist on the rows,
+whatever `T` claims; and a call passing only `ViewID`/`ViewName` (no `EntityName`, no loaded
+`ViewEntity`) skips normalization — pass `EntityName` alongside the view identifier to get
+normalized rows.
+
+**Rule of thumb: want entity behavior — methods, validation, save, related records — ask for
+entity objects.** Choose `'simple'` for cheap read-only rows; its dates and numbers are already
+the types your entity declares.
+
 #### Batch Multiple Views
 
 Use `RunViews` (plural) to execute multiple independent queries in a single operation.
@@ -1747,7 +1810,7 @@ This library is written in TypeScript and provides full type definitions. All ge
 
 ## License
 
-ISC License - see LICENSE file for details.
+Business Source License 1.1 - see LICENSE file for details.
 
 ## Remote Operations (the 4th Data Primitive)