@memberjunction/core 5.51.0 → 6.1.0-edge.1

package/readme.md

@@ -130,7 +130,13 @@ flowchart LR
 | `securityInfo.ts` | Security classes: `UserInfo`, `RoleInfo`, `AuthorizationInfo`, `AuditLogTypeInfo` |
 | `interfaces.ts` | Core interfaces: `IMetadataProvider`, `IEntityDataProvider`, `IRunViewProvider`, etc. |
 | `compositeKey.ts` | `CompositeKey` and `KeyValuePair` for multi-field primary key support |
-| `transactionGroup.ts` | `TransactionGroupBase` for atomic multi-entity operations |
+| `transactionGroup.ts` | `TransactionGroupBase` — an *arbitrary batch* facility for shipping unrelated records in one atomic round trip (saves are deferred; not for parent/children) |
+| `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 |
+| `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 |
 | `baseEngine.ts` | `BaseEngine` abstract singleton for building services with auto-loaded data |
 | `runQuery.ts` | `RunQuery` class for secure parameterized query execution |
 | `runReport.ts` | `RunReport` class for report generation |
@@ -796,6 +802,127 @@ const results = await txGroup.Submit();
 
 Each `TransactionResult` in the returned array contains a `Success` flag. If any operation fails, all are rolled back.
 
+> **A TransactionGroup is an *arbitrary batch* facility, not a composite-save engine.** Under a
+> transaction group `Save()` **defers**: the provider only registers an instruction, so the entity
+> returns `true` before anything persists, the primary key is unavailable afterwards, there is no
+> read-your-writes, and ordering is array position with a flat `Define`/`Use` variable namespace.
+> To save a parent *and its children*, use an **entity graph** (below), not a transaction group.
+> Full comparison: [Transactions, Batching & Entity Graphs](../../guides/TRANSACTIONS_AND_BATCHING_GUIDE.md).
+
+---
+
+### Entity Companions & Composite Graph Saves
+
+A **companion** is named, serialisable state attached to a record that is not one of its fields —
+most commonly a collection of child records. Companions load, validate, serialise and persist with
+their parent, on **both tiers**, from one call: `entity.Save()`.
+
+Declare a child collection on a **shared (client + server)** entity subclass:
+
+```typescript
+@RegisterClass(BaseEntity, 'MJ_BizApps_Orders: Orders')
+export class OrderEntity extends mjBizAppsOrdersOrderEntity {
+    public readonly Lines = this.DeclareRelatedRecords<OrderLineEntity>({
+        Name: 'Lines',
+        RelatedEntity: 'MJ_BizApps_Orders: Order Lines',
+        RelatedEntityJoinField: 'OrderHeaderID',
+        OrderBy: 'LineNumber ASC',
+        Load: 'explicit',                        // 'explicit' | 'immediate' | 'lazy' | 'never'
+        OnRemove: 'delete',                      // 'delete' | 'orphan' | 'refuse'
+        Sequence: { Field: 'LineNumber', From: 1 },
+    });
+
+    public override Validate(): ValidationResult {
+        const result = super.Validate();         // fans out to every companion
+        assertHasLines(this.Lines.Items, result);// sees the WHOLE graph, before any write
+        return result;
+    }
+}
+```
+
+```typescript
+const order = await md.GetEntityObject<OrderEntity>('MJ_BizApps_Orders: Orders');
+order.NewRecord();
+(await order.Lines.Create()).Quantity = 2;
+(await order.Lines.Create()).Quantity = 5;
+await order.Save();      // header + both lines, atomically
+```
+
+**How it executes.** `Save()` builds an `EntitySavePlan`. A single-node plan takes the ordinary
+save path unchanged. A multi-node plan runs:
+
+| Provider | Behaviour |
+|---|---|
+| `SupportsEntityTransactions === true` (server) | Executes locally inside one transaction scope |
+| `false` (browser) | Serialises the graph and routes the whole unit of work to the server via the `MJ.SaveEntityGraph` remote operation, which rebuilds the records as their **server-side** subclasses and runs the same local executor there |
+
+There is exactly one cascade implementation; the remote path relocates it rather than
+reimplementing it.
+
+**Platform guarantees are preserved.** Every node is persisted via that record's own `Save()` /
+`Delete()` — never direct SQL — so Record Changes, entity actions, validation, subclass overrides,
+`PreSave` hooks, `save_started` / `save` / `delete` events and cache invalidation all fire per node.
+The root additionally raises `graph_save_started` and `graph_save` so a UI can refresh once per unit
+of work.
+
+**Loading.** `Load: 'immediate'` is honoured by `Load()` and **never** by `LoadFromData()` — that method
+is the per-row materialisation path for `RunView(ResultType:'entity_object')`, so loading children
+there degrades a view into N+1 queries. For result sets, ask for children explicitly and get one
+batched query per collection:
+
+```typescript
+const result = await rv.RunView<OrderEntity>({
+    EntityName: 'MJ_BizApps_Orders: Orders',
+    ResultType: 'entity_object',
+    IncludeRelatedRecords: ['Lines'],   // 1 query for ALL orders' lines, not one per order
+});
+```
+
+#### Declaring one without writing code
+
+Set `EntityRelationship.RelatedRecordCollection` (a JSONType blob) and CodeGen emits the declaration
+onto the **generated** entity class, so both tiers get it and no subclass is needed. `RelatedEntity`
+and `RelatedEntityJoinField` stay as columns on that same row rather than being repeated in the JSON
+— one source of truth each.
+
+#### Reading from an engine cache instead of the database
+
+```typescript
+{ Name: 'Params', Source: 'cache', Load: 'lazy' }   // ReadOnly defaults to true here
+```
+
+`Source: 'cache'` finds whichever loaded `BaseEngine` already holds the entity — generically, via
+`BaseEngineRegistry` — and filters it by the join field. **Zero queries**, and it falls back to a
+database load on a miss. Read-only (the default for `cache`) hands out the engine's own instances as
+a *live view*; writable copies them so the cache is never mutated in place.
+
+`Load: 'lazy'` fills on first read of `Items`, reproducing a hand-written memoised getter — and
+**throws** rather than returning an empty array when no engine caches the entity, because a lazy
+declaration asserts that one does.
+
+```typescript
+await action.LoadRelatedRecords();   // cache-backed free, database-backed batched into ONE RunViews
+```
+
+```typescript
+for (const line of order.Lines) { … }   // the collection is ITERABLE
+const all = [...order.Lines];            // spread and destructuring work
+order.Lines.length                       // and length
+order.Lines.Items.map(l => l.Total)      // Items for map/filter/find — it is readonly, so nothing
+                                         // can push around the removal tracking and sequencing
+```
+
+**Key APIs:** `BaseEntity.DeclareRelatedRecords()`, `LoadRelatedRecords()`, `RegisterCompanion()`,
+`GetCompanion()`, `Companions`, `SerializeCompanions()`, `DeserializeCompanions()`;
+`RelatedRecordCollection<T>` (iterable; `Items`, `Removed`, `Count`/`length`, `Add`, `Create`,
+`Remove`, `Clear`, `Load`, `Dirty`, `Source`, `IsReadOnly`, `LoadMode`, `RemovalMode`); `EntityCompanion` (subclass for a new *kind* of companion);
+`EntitySavePlan`.
+
+**Full guide — with flow diagrams for the local save and the network round trip:**
+[Related-Record Collections](./docs/related-record-collections.md). For when to use this versus a
+provider transaction versus a TransactionGroup, see
+[Transactions, Batching & Entity Graphs](../../guides/TRANSACTIONS_AND_BATCHING_GUIDE.md).
+
 ---
 
 ### Datasets
@@ -1185,9 +1312,31 @@ abstract class DatabaseProviderBase extends ProviderBase {
     abstract BeginTransaction(): Promise<void>;
     abstract CommitTransaction(): Promise<void>;
     abstract RollbackTransaction(): Promise<void>;
+
+    // The unified, provider-arbitrated transaction primitive (6.2+). Starts a transaction or joins
+    // one already in flight. Used by IS-A chains, composite graph saves, and application cascades
+    // alike — so none of them has to know about the others.
+    get SupportsEntityTransactions(): boolean;                    // true here, false on ProviderBase
+    BeginEntityTransaction(): Promise<EntityTransactionScope>;
 }
 ```
 
+**Prefer `BeginEntityTransaction()` / `RunInEntityTransaction()` over calling `BeginTransaction()`
+directly.** The scope is settle-once and composes with any transaction already open:
+
+```typescript
+import { RunInEntityTransaction } from '@memberjunction/core';
+
+await RunInEntityTransaction(this.ProviderToUse, async () => {
+    await header.Save();
+    for (const line of lines) { line.HeaderID = header.ID; await line.Save(); }
+});
+```
+
+See [Transactions, Batching & Entity Graphs](../../guides/TRANSACTIONS_AND_BATCHING_GUIDE.md) for
+the difference between provider transactions, Transaction Groups, and entity graphs — and for why
+the `BeginISATransaction` trio was retired in 6.2.
+
 ---
 
 ## Provider Architecture
@@ -1663,6 +1812,14 @@ flowchart LR
 | `AllowUpdateAPI` | Configurable | Always `false` |
 | Stored procedures | Generated | None |
 
+> **Not the same thing as a custom base view.** A virtual entity has *no base table* and is read-only.
+> If you have a real table and only want to add computed columns to what its view exposes, you want a
+> **layered base view** instead — `GeneratedBaseViewName` keeps CodeGen generating an inner view while
+> your application owns and wraps `BaseView`, and the entity stays fully writable because
+> `spCreate`/`spUpdate`/`spDelete` still target `BaseView`. See
+> [Base Views: Generated, Custom, or Layered](../CodeGenLib/README.md#base-views-generated-custom-or-layered).
+> Layering is skipped entirely for virtual entities, which have no table to generate from.
+
 ### Read-Only Enforcement
 
 Virtual entities are enforced as read-only at multiple layers:
@@ -1891,6 +2048,7 @@ For detailed guides on specific topics, see the [docs/](./docs/) folder:
 
 - [Virtual Entities](./docs/virtual-entities.md) — Config-driven creation, LLM decoration, read-only enforcement
 - [IS-A Relationships](./docs/isa-relationships.md) — Type inheritance, save/delete orchestration, provider integration
+- [Related-Record Collections](./docs/related-record-collections.md) — Parent + its FK rows as one unit: metadata declaration, the local save flow and the one-call network round trip (both diagrammed), cache-backed sources, load modes, sequencing and the cycle guard
 - [Organic Keys](./docs/organic-keys.md) — Cross-system matching by shared business data (email, phone, domain), CodeGen integration, transitive views
 - [RunQuery Pagination](./docs/runquery-pagination.md) — Parameterized queries with pagination support
 - [Full-Text Search](./docs/FULL_TEXT_SEARCH_GUIDE.md) — Database-native FTS via `Metadata.FullTextSearch()`, SQL Server FREETEXT / PostgreSQL tsvector, provider architecture, Knowledge Hub integration

package/dist/generic/runReport.d.ts

@@ -1,25 +0,0 @@
-import { IRunReportProvider, RunReportResult } from './interfaces.js';
-import { UserInfo } from './securityInfo.js';
-export type RunReportParams = {
-    ReportID: string;
-};
-/**
- * Class used to run a report and return the results.
- */
-export declare class RunReport {
-    private _provider;
-    /**
-     * Optionally, you can pass in a provider to use for running the report. If you dont pass in a provider, the static provider will be used.
-     * @param provider
-     */
-    constructor(provider?: IRunReportProvider | null);
-    /**
-     * Returns the provider to be used for this instance, if one was passed in. Otherwise, it returns the static provider.
-     */
-    get ProviderToUse(): IRunReportProvider;
-    RunReport(params: RunReportParams, contextUser?: UserInfo): Promise<RunReportResult>;
-    private static _globalProviderKey;
-    static get Provider(): IRunReportProvider;
-    static set Provider(value: IRunReportProvider);
-}
-//# sourceMappingURL=runReport.d.ts.map

package/dist/generic/runReport.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"runReport.d.ts","sourceRoot":"","sources":["../../src/generic/runReport.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,MAAM,MAAM,eAAe,GAAG;IAC1B,QAAQ,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;GAEG;AACH,qBAAa,SAAS;IAClB,OAAO,CAAC,SAAS,CAAqB;IACtC;;;OAGG;gBACS,QAAQ,GAAE,kBAAkB,GAAG,IAAW;IAItD;;OAEG;IACH,IAAW,aAAa,IAAI,kBAAkB,CAE7C;IAEY,SAAS,CAAC,MAAM,EAAE,eAAe,EAAE,WAAW,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,eAAe,CAAC;IAIjG,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAkC;IACnE,WAAkB,QAAQ,IAAI,kBAAkB,CAM/C;IACD,WAAkB,QAAQ,CAAC,KAAK,EAAE,kBAAkB,EAMnD;CAEJ"}

package/dist/generic/runReport.js

@@ -1,38 +0,0 @@
-import { MJGlobal } from '@memberjunction/global';
-/**
- * Class used to run a report and return the results.
- */
-export class RunReport {
-    /**
-     * Optionally, you can pass in a provider to use for running the report. If you dont pass in a provider, the static provider will be used.
-     * @param provider
-     */
-    constructor(provider = null) {
-        this._provider = provider;
-    }
-    /**
-     * Returns the provider to be used for this instance, if one was passed in. Otherwise, it returns the static provider.
-     */
-    get ProviderToUse() {
-        return this._provider || RunReport.Provider;
-    }
-    async RunReport(params, contextUser) {
-        return this.ProviderToUse.RunReport(params, contextUser);
-    }
-    static { this._globalProviderKey = 'MJ_RunReportProvider'; }
-    static get Provider() {
-        const g = MJGlobal.Instance.GetGlobalObjectStore();
-        if (g)
-            return g[RunReport._globalProviderKey];
-        else
-            throw new Error('No global object store, so we cant get the static provider');
-    }
-    static set Provider(value) {
-        const g = MJGlobal.Instance.GetGlobalObjectStore();
-        if (g)
-            g[RunReport._globalProviderKey] = value;
-        else
-            throw new Error('No global object store, so we cant set the static provider');
-    }
-}
-//# sourceMappingURL=runReport.js.map

package/dist/generic/runReport.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"runReport.js","sourceRoot":"","sources":["../../src/generic/runReport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAQlD;;GAEG;AACH,MAAM,OAAO,SAAS;IAElB;;;OAGG;IACH,YAAY,WAAsC,IAAI;QAClD,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;IAC9B,CAAC;IAED;;OAEG;IACH,IAAW,aAAa;QACpB,OAAO,IAAI,CAAC,SAAS,IAAI,SAAS,CAAC,QAAQ,CAAC;IAChD,CAAC;IAEM,KAAK,CAAC,SAAS,CAAC,MAAuB,EAAE,WAAsB;QAClE,OAAO,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC7D,CAAC;aAEc,uBAAkB,GAAW,sBAAsB,CAAC;IAC5D,MAAM,KAAK,QAAQ;QACtB,MAAM,CAAC,GAAG,QAAQ,CAAC,QAAQ,CAAC,oBAAoB,EAAE,CAAC;QACnD,IAAI,CAAC;YACD,OAAO,CAAC,CAAC,SAAS,CAAC,kBAAkB,CAAC,CAAC;;YAEvC,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;IACtF,CAAC;IACM,MAAM,KAAK,QAAQ,CAAC,KAAyB;QAChD,MAAM,CAAC,GAAG,QAAQ,CAAC,QAAQ,CAAC,oBAAoB,EAAE,CAAC;QACnD,IAAI,CAAC;YACD,CAAC,CAAC,SAAS,CAAC,kBAAkB,CAAC,GAAG,KAAK,CAAC;;YAExC,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;IACtF,CAAC"}