@memberjunction/record-graph 0.0.1-seed.1 → 6.2.0-edge.3

package/LICENSE

@@ -0,0 +1,183 @@
+Business Source License 1.1
+
+License text copyright (c) 2024 MariaDB plc, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB plc.
+
+-----------------------------------------------------------------------------
+
+Parameters
+
+Licensor:             Blue Cypress, Inc.
+
+Licensed Work:        MemberJunction.
+                      The Licensed Work is (c) 2023-2026 Blue Cypress, Inc.
+
+Additional Use Grant: Subject to the terms of this License, Licensor grants
+                      you the following additional rights to make Production
+                      Use of the Licensed Work.
+
+                      1. Internal Use
+
+                      You may make production use of the Licensed Work for
+                      your own internal business or organizational operations.
+
+                      2. Nonprofit Use
+
+                      If you are a Nonprofit, you may make production use of
+                      the Licensed Work for the operations and activities of
+                      your Organizational Family.
+
+                      3. MemberJunction Certified Program Use
+
+                      If you are authorized by Licensor under the
+                      MemberJunction Certified Program to provide professional
+                      services using the Licensed Work, you may make
+                      production use of the Licensed Work in providing such
+                      professional services to a client, provided that:
+
+                      (a) the Licensed Work is deployed in, and the applicable
+                      production use occurs within, an environment owned,
+                      leased, licensed, subscribed to, or otherwise controlled
+                      by that client; and
+
+                      (b) the production use is for that client's own internal
+                      business or organizational operations or is otherwise
+                      independently permitted to that client under this
+                      Additional Use Grant.
+
+                      4. Definitions Applicable to the Additional Use Grant
+
+                      "Affiliate" means, with respect to a specified Person,
+                      any other Person that directly or indirectly Controls,
+                      is Controlled by, or is under common Control with such
+                      specified Person.
+
+                      "Control" (including the terms "Controls," "Controlled
+                      by," and "under common Control with") means the direct
+                      or indirect possession of the power to direct or cause
+                      the direction of the management and policies of a
+                      Person, whether through ownership of voting interests,
+                      by contract, or otherwise.
+
+                      "Organizational Family" means, with respect to a Person,
+                      (a) such Person and its Affiliates, and (b) any
+                      nonprofit organization, governmental entity, chapter,
+                      division, local affiliate, regional affiliate, state
+                      affiliate, national affiliate, or other entity that is
+                      formally affiliated with such Person through governing
+                      documents, a charter, bylaws, a membership agreement, or
+                      another written organizational instrument, and is
+                      recognized under such documents as part of the same
+                      organizational structure.
+
+                      "Nonprofit" means a Person recognized by the Internal
+                      Revenue Service as exempt from federal income taxation
+                      under Section 501(c)(3), 501(c)(4), 501(c)(5), or
+                      501(c)(6) of the Internal Revenue Code, or a foreign
+                      organization recognized under substantially equivalent
+                      laws.
+
+                      A Person claiming eligibility as a Nonprofit shall, upon
+                      Licensor's reasonable request, provide documentation
+                      reasonably sufficient to demonstrate that it qualifies
+                      as a Nonprofit. If such Person materially misrepresents,
+                      or is unable to demonstrate, its qualification as a
+                      Nonprofit, the rights granted to such Person under
+                      Section 2 of this Additional Use Grant shall terminate.
+
+                      "MemberJunction Certified Program" means Licensor's
+                      then-current program for certifying and authorizing a
+                      Person to provide professional services using the
+                      Licensed Work.
+
+                      "Person" means any individual, corporation, limited
+                      liability company, partnership, association, nonprofit
+                      organization, governmental entity, or other legal or
+                      organizational entity.
+
+Change Date:          Four (4) years from the date the Licensed Work is first
+                      made available.
+
+Change License:       MIT License.
+
+For information about alternative licensing arrangements for the Licensed
+Work, please contact Blue Cypress, Inc.
+
+-----------------------------------------------------------------------------
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+-----------------------------------------------------------------------------
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License
+   can be included in a program with software provided under GPL Version 2.0
+   or a later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.
+
+-----------------------------------------------------------------------------
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.

package/README.md

@@ -1,4 +1,88 @@
 # @memberjunction/record-graph
-Seed release published over OIDC to prove trusted publishing is configured for
-this package. It contains no code and is tagged `seed`, never `latest`.
-Real releases are published by .github/workflows/publish.yml.
+
+Generalized record dependency graph traversal, relationship collection resolution, topological sorting, link value encoding, and graph models for MemberJunction.
+
+Shared across:
+- **Version History**: Snapshot creation, dependency tracking, rollback / restore topological ordering.
+- **Record Cloning**: Deep copying of record graphs, subtype rows, child collections, and soft-link rewriting.
+- **Metadata Sync**: Deterministic 4-tier collection resolution and schema composition.
+
+## Installation
+
+```bash
+npm install @memberjunction/record-graph
+```
+
+## Key Components
+
+### 1. `DependencyGraphWalker`
+
+Walks an entity record's relationships to discover all dependent and referenced records.
+
+```typescript
+import { CompositeKey } from '@memberjunction/core';
+import { DependencyGraphWalker } from '@memberjunction/record-graph';
+
+const walker = new DependencyGraphWalker(provider); // provider is optional; defaults to Metadata.Provider
+const userKey = CompositeKey.FromID(userId);
+const rootNode = await walker.WalkDependents(
+  'MJ: Users',
+  userKey,
+  {
+    MaxDepth: 3,
+    RequireTrackRecordChanges: false, // Set false for cloning, true for Version History
+    IncludeSubtypes: true,            // Include IS-A subtype rows
+    FollowHierarchies: true,          // Recurse self-referencing hierarchy fields
+    EdgePolicy: (candidate) => {
+      if (candidate.TargetEntityName === 'MJ: Audit Logs') return 'Skip';
+      if (candidate.Kind === 'ForwardFK') return 'Reference';
+      return 'Deep';
+    },
+  },
+  contextUser
+);
+
+const flatNodes = walker.FlattenTopological(rootNode);
+```
+
+#### Traversal Rules & Discovery Modes
+
+- **Reverse Walk (Owned Children)**: Curated One-To-Many relationships (`EntityRelationshipInfo`) are walked with full discovery (both reverse and forward), discovering all dependent child records.
+- **Forward Walk (Referenced Records)**: Foreign key fields are walked in `forward-only` mode so referenced entities (e.g., shared lookup tables) do not traverse their own children, preventing graph explosion.
+- **Subtypes (`IncludeSubtypes`)**: Discovers IS-A subtype rows via `FindISAChildEntities`.
+- **Hierarchies (`FollowHierarchies`)**: Allows controlled recursion on fields whose `Configuration.Hierarchy.IsHierarchy` is true.
+- **Soft Links (`IncludeSoftLinks`)**: Traverses polymorphic `EntityID`/`RecordID` pairs via `EntityIDFieldName`.
+- **Non-Curated Inbound FKs (`ListNonCuratedInbound`)**: Discovers database foreign keys pointing to the record that lack a curated `EntityRelationship`.
+- **Edge Policy (`EdgePolicy`)**: Pre-traversal callback returning `'Deep'`, `'Reference'`, or `'Skip'`.
+- **Cycle Prevention**: Global `visited` set and entity-type `ancestorStack` to prevent infinite loops and backtracking.
+
+### 2. Topological Sorting (`sort.ts`)
+
+- `SortByEntityDependencyOrder<T>(items, getEntityID, provider?)`:
+  Computes DAG levels from foreign keys and sorts parent entities before child entities. Handles cycles safely.
+- `SortEntitiesByDependency`:
+  Backward-compatible alias for `SortByEntityDependencyOrder`.
+- `SortNodesTopologically(root: DependencyNode)`:
+  Breadth-first traversal flattening a dependency tree into an execution-safe array where parents precede children.
+
+### 3. Link Value Encoding (`links.ts`)
+
+- `ResolveLinkValue(kindOrIsSoft, targetKey)`:
+  Resolves the value to write into a pointer or foreign key column:
+  - Hard link (`'hard'` or `false`): bare primary key value (`targetKey.GetValueByIndex(0)`).
+  - Soft link (`'soft'` or `true`): canonical prefixed polymorphic encoding (`targetKey.ToRecordID()`).
+
+### 4. Collection Resolver (`collection-resolver.ts`)
+
+- `ResolveCollectionRelationship(entityInfo, colName)` (`resolveCollectionRelationship` is a deprecated alias):
+  Resolves a collection name to its matching relationship on the entity using strict 4-tier rule strength:
+  1. Explicit collection name in `RelatedRecordCollection` JSON (`"Name": "..."`)
+  2. Relationship `DisplayName`
+  3. `RelatedEntity` full name
+  4. Stripped `RelatedEntity` name (with singular/plural tolerance)
+
+### 5. SQL & Key Utilities (`sql.ts`, `keys.ts`)
+
+- `SqlEquals`, `SqlContains`, `SqlIn`, `SqlNotIn`: Safe SQL filter builders (they escape with `EscapeSQLString` from `@memberjunction/global`).
+- `BuildCompositeKeyFromRecord`, `BuildPrimaryKeyForLoad`, `BuildIdKey`: CompositeKey construction utilities.
+- The camelCase names (`sqlEquals`, `buildIdKey`, …) and `escapeSqlString` are deprecated aliases. Use `EscapeSQLString` from `@memberjunction/global` directly.

package/dist/DependencyGraphWalker.d.ts

@@ -0,0 +1,129 @@
+import { CompositeKey, EntityInfo, IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { DependencyNode, WalkOptions } from './types.js';
+/**
+ * Extended metadata provider interface with optional FindISAChildEntities
+ */
+interface IExtendedMetadataProvider extends IMetadataProvider {
+    FindISAChildEntities?(entityInfo: EntityInfo, recordPKValue: string, contextUser?: UserInfo): Promise<{
+        ChildEntityName: string;
+    }[]>;
+}
+/**
+ * Walks a record's relationship graph to discover all dependent and referenced records.
+ *
+ * Traversal rules:
+ * - Reverse walk: follows curated One-To-Many relationships (where child points to parent).
+ *   Recurses with 'full' mode (both reverse + forward).
+ * - Forward walk: follows foreign keys on the parent (where parent points to another entity).
+ *   Recurses with 'forward-only' mode — targets do NOT discover their own reverse children,
+ *   preventing graph explosion from shared/hub entities.
+ * - Subtypes: follows IS-A inheritance if IncludeSubtypes is true.
+ * - Hierarchies: follows self-referencing hierarchy FKs if FollowHierarchies is true.
+ * - Soft links: follows inbound polymorphic EntityID/RecordID links if IncludeSoftLinks is true.
+ * - Non-curated inbound FKs: discovers non-curated inbound FKs if ListNonCuratedInbound is true.
+ * - EdgePolicy: callers can supply an EdgePolicy callback to dictate Deep / Reference / Skip per edge.
+ * - Cycle prevention: uses ancestorStack (entity types) to prevent backtracking and a global visited set (records).
+ */
+export declare class DependencyGraphWalker {
+    /** Cache: entityID → reverse relationships from EntityRelationship metadata */
+    private reverseRelCache;
+    /** Cache: entityID → forward FK references from field metadata */
+    private forwardRefCache;
+    /** Optional provider override; falls back to Metadata.Provider when not set. */
+    private _provider?;
+    constructor(provider?: IMetadataProvider);
+    /** Returns the active provider — explicit override if set, otherwise the global default. */
+    protected get ProviderToUse(): IExtendedMetadataProvider;
+    /**
+     * Walk from a root record through its relationships, building a tree of
+     * all records that should be included in a version label or clone plan.
+     *
+     * @param entityName - The starting entity name
+     * @param recordKey  - The starting record's primary key
+     * @param options    - Controls depth, filtering, policies, etc.
+     * @param contextUser - Server-side user context
+     * @returns The root DependencyNode with all descendants populated
+     */
+    WalkDependents(entityName: string, recordKey: CompositeKey, options: WalkOptions, contextUser: UserInfo): Promise<DependencyNode>;
+    /**
+     * Flatten a dependency tree into a topologically sorted list.
+     * Parents appear before their children, ensuring safe restore or clone execution ordering.
+     */
+    FlattenTopological(root: DependencyNode): DependencyNode[];
+    /**
+     * Recursively discover and attach child nodes for a given parent node.
+     */
+    private walkChildren;
+    /**
+     * Walk reverse relationships: for each EntityRelationship on the parent
+     * entity, load matching child records and recurse into them.
+     */
+    private walkReverseRelationships;
+    /**
+     * Discovers inbound foreign keys that are not registered as curated EntityRelationships.
+     * Evaluated when ListNonCuratedInbound is true.
+     */
+    private walkNonCuratedInbound;
+    /**
+     * Discovers records pointing to the parent via polymorphic EntityID/RecordID soft links.
+     */
+    private walkSoftLinks;
+    /**
+     * Discover and attach IS-A subtype rows for a given parent record.
+     */
+    private walkSubtypes;
+    /**
+     * Walk forward FK references: for each FK field on the parent entity that
+     * points to another entity, load the referenced record and recurse.
+     */
+    private walkForwardReferences;
+    /**
+     * Discover reverse relationships for an entity using EntityRelationship metadata.
+     */
+    private discoverReverseRelationships;
+    /**
+     * Discover forward FK references on an entity.
+     */
+    private discoverForwardReferences;
+    /**
+     * Load child records for a reverse relationship.
+     */
+    private loadChildRecords;
+    /**
+     * Load a single record's data by primary key.
+     */
+    private loadRecordData;
+    /**
+     * Build a DependencyNode from record data, register it in the visited set,
+     * and attach it as a child of the parent. Returns null if already visited.
+     */
+    private registerNode;
+    /** Create an empty stats accumulator. */
+    private createEmptyStats;
+    /** Increment the per-entity record counter. */
+    private incrementEntityCount;
+    /**
+     * Log a detailed summary of the walk.
+     */
+    private logWalkSummary;
+    /** Build a unique key for the visited set: "EntityName::recordID" */
+    private visitKey;
+    /**
+     * Determine the parent key field from an EntityRelationship record.
+     */
+    private resolveParentKeyFieldFromRelationship;
+    /**
+     * Determine the target key field from a FK field definition.
+     */
+    private resolveParentKeyFieldFromFK;
+    /** Check if a field name matches a system/infrastructure FK pattern. */
+    private isSystemFKField;
+    /** Check if an entity should be skipped based on filter options. */
+    private shouldSkipEntity;
+    /** Check if an entity has a soft delete field. */
+    private entityHasSoftDelete;
+    /** Apply defaults to walk options. */
+    private resolveDefaults;
+}
+export {};
+//# sourceMappingURL=DependencyGraphWalker.d.ts.map

package/dist/DependencyGraphWalker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DependencyGraphWalker.d.ts","sourceRoot":"","sources":["../src/DependencyGraphWalker.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,YAAY,EAEZ,UAAU,EAEV,iBAAiB,EAIjB,QAAQ,EACX,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACH,cAAc,EAKd,WAAW,EAEd,MAAM,SAAS,CAAC;AA+BjB;;GAEG;AACH,UAAU,yBAA0B,SAAQ,iBAAiB;IACzD,oBAAoB,CAAC,CACjB,UAAU,EAAE,UAAU,EACtB,aAAa,EAAE,MAAM,EACrB,WAAW,CAAC,EAAE,QAAQ,GACvB,OAAO,CAAC;QAAE,eAAe,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC,CAAC;CAC7C;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,qBAAqB;IAC9B,+EAA+E;IAC/E,OAAO,CAAC,eAAe,CAA4C;IACnE,kEAAkE;IAClE,OAAO,CAAC,eAAe,CAAyC;IAEhE,gFAAgF;IAChF,OAAO,CAAC,SAAS,CAAC,CAAoB;gBAEnB,QAAQ,CAAC,EAAE,iBAAiB;IAI/C,4FAA4F;IAC5F,SAAS,KAAK,aAAa,IAAI,yBAAyB,CAEvD;IAMD;;;;;;;;;OASG;IACU,cAAc,CACvB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,YAAY,EACvB,OAAO,EAAE,WAAW,EACpB,WAAW,EAAE,QAAQ,GACtB,OAAO,CAAC,cAAc,CAAC;IA6C1B;;;OAGG;IACI,kBAAkB,CAAC,IAAI,EAAE,cAAc,GAAG,cAAc,EAAE;IAQjE;;OAEG;YACW,YAAY;IAyC1B;;;OAGG;YACW,wBAAwB;IA8GtC;;;OAGG;YACW,qBAAqB;IAiGnC;;OAEG;YACW,aAAa;IA+F3B;;OAEG;YACW,YAAY;IAgF1B;;;OAGG;YACW,qBAAqB;IAwJnC;;OAEG;IACH,OAAO,CAAC,4BAA4B;IAkDpC;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAuCjC;;OAEG;YACW,gBAAgB;IAyC9B;;OAEG;YACW,cAAc;IA0B5B;;;OAGG;IACH,OAAO,CAAC,YAAY;IAyCpB,yCAAyC;IACzC,OAAO,CAAC,gBAAgB;IAUxB,+CAA+C;IAC/C,OAAO,CAAC,oBAAoB;IAK5B;;OAEG;IACH,OAAO,CAAC,cAAc;IA0BtB,qEAAqE;IACrE,OAAO,CAAC,QAAQ;IAIhB;;OAEG;IACH,OAAO,CAAC,qCAAqC;IAU7C;;OAEG;IACH,OAAO,CAAC,2BAA2B;IAUnC,wEAAwE;IACxE,OAAO,CAAC,eAAe;IAIvB,oEAAoE;IACpE,OAAO,CAAC,gBAAgB;IAUxB,kDAAkD;IAClD,OAAO,CAAC,mBAAmB;IAI3B,sCAAsC;IACtC,OAAO,CAAC,eAAe;CAe1B"}