@memberjunction/record-cloning-base 0.0.0 → 6.2.0-edge.2

package/dist/FieldMeta.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @file FieldMeta.ts
+ * Builds the field metadata the field mapper and the config validator read, from an entity's
+ * `EntityInfo`. The planner and the Entities-form cloning panel both use it, so a field the engine
+ * treats as automatic (key, __mj timestamps, read-only view columns) is treated the same way by
+ * validation in the UI.
+ */
+import type { EntityInfo, IEntityCloneConfiguration } from '@memberjunction/core';
+import type { FieldMappingFieldMeta } from './CloneFieldMapper.js';
+import type { CloneConfigEntityMeta } from './CloneConfigValidator.js';
+/** Field metadata for every field of `entity`, in the shape `MapFieldsForClone` and `CloneConfigValidator` expect. */
+export declare function FieldMetaFromEntity(entity: EntityInfo): FieldMappingFieldMeta[];
+/** The validator's view of `entity` with `config` as its clone configuration. */
+export declare function CloneConfigMetaFromEntity(entity: EntityInfo, config?: IEntityCloneConfiguration | null): CloneConfigEntityMeta;
+//# sourceMappingURL=FieldMeta.d.ts.map

package/dist/FieldMeta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FieldMeta.d.ts","sourceRoot":"","sources":["../src/FieldMeta.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAClF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAEpE,sHAAsH;AACtH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,GAAG,qBAAqB,EAAE,CAqB/E;AAED,iFAAiF;AACjF,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,yBAAyB,GAAG,IAAI,GAAG,qBAAqB,CAQ9H"}

package/dist/FieldMeta.js

@@ -0,0 +1,41 @@
+/**
+ * @file FieldMeta.ts
+ * Builds the field metadata the field mapper and the config validator read, from an entity's
+ * `EntityInfo`. The planner and the Entities-form cloning panel both use it, so a field the engine
+ * treats as automatic (key, __mj timestamps, read-only view columns) is treated the same way by
+ * validation in the UI.
+ */
+/** Field metadata for every field of `entity`, in the shape `MapFieldsForClone` and `CloneConfigValidator` expect. */
+export function FieldMetaFromEntity(entity) {
+    return entity.Fields.map((f) => ({
+        Name: f.Name,
+        IsPrimaryKey: f.IsPrimaryKey,
+        IsIdentity: f.AutoIncrement === true,
+        IsNameField: entity.NameField?.Name.toLowerCase() === f.Name.toLowerCase() || f.Name.toLowerCase() === 'name',
+        IsUnique: f.IsUnique,
+        RelatedEntityID: f.RelatedEntityID,
+        RelatedEntity: f.RelatedEntity,
+        RelatedEntityJoinField: f.RelatedEntityFieldName,
+        EntityIDFieldName: f.EntityIDFieldName,
+        Type: f.Type,
+        IsSPParameter: (upd) => (f.IsSPParameter ? f.IsSPParameter(upd) : true),
+        DefaultValue: f.DefaultValue,
+        AllowsNull: f.AllowsNull,
+        IsCreatedAtField: f.Name === '__mj_CreatedAt',
+        IsUpdatedAtField: f.Name === '__mj_UpdatedAt',
+        IsSoftDeleteField: false,
+        Encrypted: f.Encrypt === true,
+        MaxLength: f.MaxLength,
+    }));
+}
+/** The validator's view of `entity` with `config` as its clone configuration. */
+export function CloneConfigMetaFromEntity(entity, config) {
+    return {
+        Name: entity.Name,
+        // Same field flags the planner uses, so automatic fields aren't reported as unclassified.
+        Fields: FieldMetaFromEntity(entity),
+        Relationships: (entity.RelatedEntities ?? []).map((r) => ({ ID: r.ID, RelatedEntity: r.RelatedEntity, RelatedEntityJoinField: r.RelatedEntityJoinField })),
+        CloneConfiguration: (config ?? undefined),
+    };
+}
+//# sourceMappingURL=FieldMeta.js.map

package/dist/FieldMeta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FieldMeta.js","sourceRoot":"","sources":["../src/FieldMeta.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,sHAAsH;AACtH,MAAM,UAAU,mBAAmB,CAAC,MAAkB;IAClD,OAAO,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC7B,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,YAAY,EAAE,CAAC,CAAC,YAAY;QAC5B,UAAU,EAAE,CAAC,CAAC,aAAa,KAAK,IAAI;QACpC,WAAW,EAAE,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,MAAM;QAC7G,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,eAAe,EAAE,CAAC,CAAC,eAAe;QAClC,aAAa,EAAE,CAAC,CAAC,aAAa;QAC9B,sBAAsB,EAAE,CAAC,CAAC,sBAAsB;QAChD,iBAAiB,EAAE,CAAC,CAAC,iBAAiB;QACtC,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,aAAa,EAAE,CAAC,GAAY,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAChF,YAAY,EAAE,CAAC,CAAC,YAAY;QAC5B,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,gBAAgB,EAAE,CAAC,CAAC,IAAI,KAAK,gBAAgB;QAC7C,gBAAgB,EAAE,CAAC,CAAC,IAAI,KAAK,gBAAgB;QAC7C,iBAAiB,EAAE,KAAK;QACxB,SAAS,EAAE,CAAC,CAAC,OAAO,KAAK,IAAI;QAC7B,SAAS,EAAE,CAAC,CAAC,SAAS;KACzB,CAAC,CAAC,CAAC;AACR,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,yBAAyB,CAAC,MAAkB,EAAE,MAAyC;IACnG,OAAO;QACH,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,0FAA0F;QAC1F,MAAM,EAAE,mBAAmB,CAAC,MAAM,CAAC;QACnC,aAAa,EAAE,CAAC,MAAM,CAAC,eAAe,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,aAAa,EAAE,CAAC,CAAC,aAAa,EAAE,sBAAsB,EAAE,CAAC,CAAC,sBAAsB,EAAE,CAAC,CAAC;QAC1J,kBAAkB,EAAE,CAAC,MAAM,IAAI,SAAS,CAA2D;KACtG,CAAC;AACN,CAAC"}

package/dist/JsonRemapEngine.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @file JsonRemapEngine.ts
+ * Path-based JSON key remapping, regeneration, and container cleanup.
+ * Client-safe with built-in presets for dashboard UI configs and scheduled jobs.
+ * @see plans/record-cloning/README.md §7.6, §13.1
+ */
+import { CloneWarning } from './types.js';
+export type JsonRemapMode = 'remap' | 'reuse' | 'regenerate' | 'null' | 'drop';
+export interface JsonRemapRule {
+    Path: string;
+    Mode: JsonRemapMode;
+    TargetEntityName?: string;
+    OnMissing?: 'reuse' | 'drop';
+    CleanEmptyContainers?: boolean;
+}
+export interface JsonRemapOptions {
+    Rules?: JsonRemapRule[];
+    Preset?: 'dashboard-ui-config' | 'scheduled-job-configuration';
+    KeyMap?: Record<string, string>;
+    OnMalformed?: 'block' | 'copy' | 'null';
+    CleanEmptyContainers?: boolean;
+}
+export interface JsonRemapResult {
+    Success: boolean;
+    Output: unknown;
+    JsonString: string;
+    DropCount: number;
+    PathsModified: string[];
+    Blocked: boolean;
+    Warning?: CloneWarning;
+}
+/** Mints a v4 UUID through MJGlobal's `Uuidv4` (crypto-backed; never `Math.random`). */
+export declare function GenerateUUID(): string;
+/**
+ * Built-in presets for common MemberJunction JSON columns.
+ */
+export declare const JSON_REMAP_PRESETS: Record<string, JsonRemapRule[]>;
+/**
+ * Parses and executes JSON remap rules on an input JSON string or object.
+ */
+export declare function ApplyJsonRemap(input: string | Record<string, unknown> | unknown[], options: JsonRemapOptions): JsonRemapResult;
+//# sourceMappingURL=JsonRemapEngine.d.ts.map

package/dist/JsonRemapEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JsonRemapEngine.d.ts","sourceRoot":"","sources":["../src/JsonRemapEngine.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,OAAO,GAAG,YAAY,GAAG,MAAM,GAAG,MAAM,CAAC;AAE/E,MAAM,WAAW,aAAa;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,aAAa,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC7B,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,gBAAgB;IAC7B,KAAK,CAAC,EAAE,aAAa,EAAE,CAAC;IACxB,MAAM,CAAC,EAAE,qBAAqB,GAAG,6BAA6B,CAAC;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,WAAW,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IACxC,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,eAAe;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,YAAY,CAAC;CAC1B;AAED,wFAAwF;AACxF,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,EAAE,CAe9D,CAAC;AAEF;;GAEG;AACH,wBAAgB,cAAc,CAC1B,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,EAAE,EACnD,OAAO,EAAE,gBAAgB,GAC1B,eAAe,CA+LjB"}

package/dist/JsonRemapEngine.js

@@ -0,0 +1,251 @@
+/**
+ * @file JsonRemapEngine.ts
+ * Path-based JSON key remapping, regeneration, and container cleanup.
+ * Client-safe with built-in presets for dashboard UI configs and scheduled jobs.
+ * @see plans/record-cloning/README.md §7.6, §13.1
+ */
+import { Uuidv4 } from '@memberjunction/global';
+/** Mints a v4 UUID through MJGlobal's `Uuidv4` (crypto-backed; never `Math.random`). */
+export function GenerateUUID() {
+    return Uuidv4();
+}
+/**
+ * Built-in presets for common MemberJunction JSON columns.
+ */
+export const JSON_REMAP_PRESETS = {
+    'dashboard-ui-config': [
+        { Path: 'content[*].id', Mode: 'regenerate' },
+        { Path: 'content[*].content[*].id', Mode: 'regenerate' },
+        { Path: 'content[*].componentState.config.viewId', Mode: 'remap', OnMissing: 'reuse' },
+        { Path: 'content[*].componentState.config.queryId', Mode: 'remap', OnMissing: 'reuse' },
+        { Path: 'content[*].content[*].componentState.config.viewId', Mode: 'remap', OnMissing: 'reuse' },
+        { Path: 'content[*].content[*].componentState.config.queryId', Mode: 'remap', OnMissing: 'reuse' },
+    ],
+    'scheduled-job-configuration': [
+        { Path: 'ConversationID', Mode: 'null' },
+        { Path: 'ActionParamID', Mode: 'remap', OnMissing: 'reuse' },
+        { Path: 'Params[*].ActionParamID', Mode: 'remap', OnMissing: 'reuse' },
+        { Path: 'Params[*].ParamID', Mode: 'remap', OnMissing: 'reuse' },
+    ],
+};
+/**
+ * Parses and executes JSON remap rules on an input JSON string or object.
+ */
+export function ApplyJsonRemap(input, options) {
+    const onMalformed = options.OnMalformed || 'block';
+    let data;
+    const isStringInput = typeof input === 'string';
+    if (isStringInput) {
+        if (!input || input.trim() === '') {
+            return {
+                Success: true,
+                Output: input,
+                JsonString: input,
+                DropCount: 0,
+                PathsModified: [],
+                Blocked: false,
+            };
+        }
+        try {
+            data = JSON.parse(input);
+        }
+        catch (err) {
+            if (onMalformed === 'copy') {
+                return {
+                    Success: true,
+                    Output: input,
+                    JsonString: input,
+                    DropCount: 0,
+                    PathsModified: [],
+                    Blocked: false,
+                    Warning: {
+                        Code: 'PAYLOAD_DROPPED',
+                        Severity: 'Warning',
+                        Message: 'Malformed JSON copied as-is per OnMalformed="copy".',
+                    },
+                };
+            }
+            if (onMalformed === 'null') {
+                return {
+                    Success: true,
+                    Output: null,
+                    JsonString: 'null',
+                    DropCount: 0,
+                    PathsModified: [],
+                    Blocked: false,
+                    Warning: {
+                        Code: 'PAYLOAD_DROPPED',
+                        Severity: 'Warning',
+                        Message: 'Malformed JSON nulled per OnMalformed="null".',
+                    },
+                };
+            }
+            return {
+                Success: false,
+                Output: input,
+                JsonString: input,
+                DropCount: 0,
+                PathsModified: [],
+                Blocked: true,
+                Warning: {
+                    Code: 'PAYLOAD_DROPPED',
+                    Severity: 'Error',
+                    Message: `Payload is malformed JSON and cannot be remapped: ${String(err)}`,
+                },
+            };
+        }
+    }
+    else {
+        // Clone input object so we don't mutate caller's state
+        data = JSON.parse(JSON.stringify(input));
+    }
+    // Assemble rules from preset and explicit rules
+    let rules = [];
+    if (options.Preset && JSON_REMAP_PRESETS[options.Preset]) {
+        rules.push(...JSON_REMAP_PRESETS[options.Preset]);
+    }
+    if (options.Rules) {
+        rules.push(...options.Rules);
+    }
+    let dropCount = 0;
+    const pathsModified = new Set();
+    const keyMap = options.KeyMap || {};
+    const globalCleanEmpty = options.CleanEmptyContainers ?? true;
+    for (const rule of rules) {
+        const segments = rule.Path.split('.');
+        const ruleCleanEmpty = rule.CleanEmptyContainers ?? globalCleanEmpty;
+        const processSegments = (current, segIdx, currentPath) => {
+            if (current === null || current === undefined || typeof current !== 'object') {
+                return { modified: false, dropped: false };
+            }
+            const segment = segments[segIdx];
+            const isLast = segIdx === segments.length - 1;
+            const isArraySegment = segment.endsWith('[*]');
+            const propName = isArraySegment ? segment.slice(0, -3) : segment;
+            if (isLast) {
+                if (isArraySegment) {
+                    const arr = current[propName];
+                    if (Array.isArray(arr)) {
+                        let anyModified = false;
+                        for (let i = arr.length - 1; i >= 0; i--) {
+                            const item = arr[i];
+                            const itemResult = evaluateTerminal(item, rule, keyMap);
+                            if (itemResult.action === 'drop') {
+                                arr.splice(i, 1);
+                                dropCount++;
+                                anyModified = true;
+                                pathsModified.add(`${currentPath}.${propName}[${i}]`);
+                            }
+                            else if (itemResult.action === 'update') {
+                                arr[i] = itemResult.newValue;
+                                anyModified = true;
+                                pathsModified.add(`${currentPath}.${propName}[${i}]`);
+                            }
+                        }
+                        if (ruleCleanEmpty && arr.length === 0) {
+                            delete current[propName];
+                            pathsModified.add(`${currentPath}.${propName}`);
+                        }
+                        return { modified: anyModified, dropped: false };
+                    }
+                }
+                else {
+                    const obj = current;
+                    if (propName in obj) {
+                        const val = obj[propName];
+                        const itemResult = evaluateTerminal(val, rule, keyMap);
+                        if (itemResult.action === 'drop') {
+                            delete obj[propName];
+                            dropCount++;
+                            pathsModified.add(`${currentPath}.${propName}`);
+                            return { modified: true, dropped: true };
+                        }
+                        else if (itemResult.action === 'update') {
+                            obj[propName] = itemResult.newValue;
+                            pathsModified.add(`${currentPath}.${propName}`);
+                            return { modified: true, dropped: false };
+                        }
+                    }
+                }
+                return { modified: false, dropped: false };
+            }
+            // Intermediate segment
+            if (isArraySegment) {
+                const arr = current[propName];
+                if (Array.isArray(arr)) {
+                    let anyModified = false;
+                    for (let i = arr.length - 1; i >= 0; i--) {
+                        const nextPath = `${currentPath}.${propName}[${i}]`;
+                        const res = processSegments(arr[i], segIdx + 1, nextPath);
+                        if (res.dropped) {
+                            arr.splice(i, 1);
+                            anyModified = true;
+                        }
+                        else if (res.modified) {
+                            anyModified = true;
+                        }
+                    }
+                    if (ruleCleanEmpty && arr.length === 0) {
+                        delete current[propName];
+                        pathsModified.add(`${currentPath}.${propName}`);
+                    }
+                    return { modified: anyModified, dropped: false };
+                }
+            }
+            else {
+                const obj = current;
+                if (propName in obj && obj[propName] !== null && typeof obj[propName] === 'object') {
+                    const nextPath = `${currentPath}.${propName}`;
+                    const res = processSegments(obj[propName], segIdx + 1, nextPath);
+                    if (ruleCleanEmpty && Object.keys(obj[propName]).length === 0) {
+                        delete obj[propName];
+                        pathsModified.add(`${currentPath}.${propName}`);
+                        return { modified: true, dropped: true };
+                    }
+                    return res;
+                }
+            }
+            return { modified: false, dropped: false };
+        };
+        processSegments(data, 0, '$');
+    }
+    const outputJson = JSON.stringify(data);
+    return {
+        Success: true,
+        Output: data,
+        JsonString: outputJson,
+        DropCount: dropCount,
+        PathsModified: Array.from(pathsModified),
+        Blocked: false,
+    };
+}
+function evaluateTerminal(val, rule, keyMap) {
+    const mode = rule.Mode;
+    if (mode === 'reuse') {
+        return { action: 'keep' };
+    }
+    if (mode === 'null') {
+        return { action: 'update', newValue: null };
+    }
+    if (mode === 'drop') {
+        return { action: 'drop' };
+    }
+    if (mode === 'regenerate') {
+        return { action: 'update', newValue: GenerateUUID() };
+    }
+    if (mode === 'remap') {
+        if (typeof val === 'string') {
+            // With a target entity, only that entity's clone counts: a bare key can belong to a row
+            // of another entity (integer keys repeat across tables).
+            const key = rule.TargetEntityName ? `${rule.TargetEntityName}::${val}` : val;
+            if (key in keyMap)
+                return { action: 'update', newValue: keyMap[key] };
+        }
+        if (rule.OnMissing === 'drop') {
+            return { action: 'drop' };
+        }
+        return { action: 'keep' };
+    }
+    return { action: 'keep' };
+}
+//# sourceMappingURL=JsonRemapEngine.js.map

package/dist/JsonRemapEngine.js.map

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

package/dist/NameTemplate.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @file NameTemplate.ts
+ * Naming template interpolation and collision avoidance strategy.
+ * Evaluates {Name}, {n}, {Date}, and {User} tokens and increments version numbers.
+ * @see plans/record-cloning/README.md §7.3, §13.1
+ */
+export interface NameTemplateContext {
+    SourceRecordName: string;
+    Counter?: number;
+    DateStr?: string;
+    UserName?: string;
+}
+export interface NameTemplateOptions {
+    Template?: string;
+    Strategy?: 'suffix' | 'increment' | 'prompt' | 'none';
+    Context?: Partial<NameTemplateContext>;
+    /** Column width in characters (0 or unset: unlimited). The source name is shortened so every candidate fits. */
+    MaxLength?: number;
+}
+/**
+ * The text every candidate `FindNextAvailableName` could produce starts with, for looking up
+ * existing names with a prefix match. Empty when there is no stable prefix. Taken from the
+ * candidates themselves, so shortening a long name or trimming a template for a short column
+ * can't make the lookup miss a name the search would then produce.
+ */
+export declare function NameCollisionPrefix(sourceName: string, options?: NameTemplateOptions): string;
+/**
+ * Renders a name template by interpolating supported tokens:
+ * - {Name}: Source name
+ * - {n}: Counter number (omitted if undefined or empty if counter=1 and template doesn't force it)
+ * - {Date}: Current date formatted as YYYY-MM-DD
+ * - {User}: User name or identifier
+ */
+export declare function RenderNameTemplate(template: string, ctx: NameTemplateContext): string;
+/**
+ * Implements the 'increment' naming strategy.
+ * Detects trailing versions/integers and bumps them:
+ * - "Project v1" -> "Project v2"
+ * - "Doc 1.0" -> "Doc 1.1"
+ * - "Widget (2)" -> "Widget (3)"
+ * - "Widget" -> "Widget 2"
+ */
+export declare function IncrementName(name: string): string;
+/**
+ * The next name not in `existingNames`, or null when none can be found: the column is too short
+ * for a distinct name, or every candidate within MAX_NAME_ATTEMPTS is taken. Comparison is
+ * case-insensitive, like SQL Server's default collation. The source name itself is never returned
+ * by the renaming strategies ('none' and 'prompt' leave the name to the caller).
+ */
+export declare function TryFindNextAvailableName(sourceName: string, existingNames: Set<string> | string[], options?: NameTemplateOptions): string | null;
+/**
+ * Finds the next available name for `sourceName`; see {@link TryFindNextAvailableName}. Returns the
+ * source name unchanged when no distinct name can be found.
+ */
+export declare function FindNextAvailableName(sourceName: string, existingNames: Set<string> | string[], options?: NameTemplateOptions): string;
+//# sourceMappingURL=NameTemplate.d.ts.map

package/dist/NameTemplate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NameTemplate.d.ts","sourceRoot":"","sources":["../src/NameTemplate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,mBAAmB;IAChC,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAC;IACtD,OAAO,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACvC,gHAAgH;IAChH,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAgB7F;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,mBAAmB,GAAG,MAAM,CAWrF;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CA+BlD;AAyBD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACpC,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,EACrC,OAAO,CAAC,EAAE,mBAAmB,GAC9B,MAAM,GAAG,IAAI,CAiBf;AAiDD;;;GAGG;AACH,wBAAgB,qBAAqB,CACjC,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,EACrC,OAAO,CAAC,EAAE,mBAAmB,GAC9B,MAAM,CAER"}

package/dist/NameTemplate.js

@@ -0,0 +1,193 @@
+/**
+ * @file NameTemplate.ts
+ * Naming template interpolation and collision avoidance strategy.
+ * Evaluates {Name}, {n}, {Date}, and {User} tokens and increments version numbers.
+ * @see plans/record-cloning/README.md §7.3, §13.1
+ */
+/**
+ * The text every candidate `FindNextAvailableName` could produce starts with, for looking up
+ * existing names with a prefix match. Empty when there is no stable prefix. Taken from the
+ * candidates themselves, so shortening a long name or trimming a template for a short column
+ * can't make the lookup miss a name the search would then produce.
+ */
+export function NameCollisionPrefix(sourceName, options) {
+    const strategy = options?.Strategy || 'suffix';
+    if (strategy === 'none' || strategy === 'prompt')
+        return '';
+    let prefix = null;
+    for (const candidate of nameCandidates(sourceName, options)) {
+        if (candidate === null)
+            continue;
+        if (prefix === null) {
+            prefix = candidate;
+            continue;
+        }
+        let i = 0;
+        while (i < prefix.length && i < candidate.length && prefix[i].toLowerCase() === candidate[i].toLowerCase())
+            i++;
+        prefix = prefix.slice(0, i);
+        if (prefix === '')
+            break;
+    }
+    return prefix ?? '';
+}
+/**
+ * Renders a name template by interpolating supported tokens:
+ * - {Name}: Source name
+ * - {n}: Counter number (omitted if undefined or empty if counter=1 and template doesn't force it)
+ * - {Date}: Current date formatted as YYYY-MM-DD
+ * - {User}: User name or identifier
+ */
+export function RenderNameTemplate(template, ctx) {
+    const dateVal = ctx.DateStr || new Date().toISOString().slice(0, 10);
+    const userVal = ctx.UserName || '';
+    const counterVal = ctx.Counter !== undefined ? String(ctx.Counter) : '';
+    return template
+        .replace(/\{Name\}/g, () => ctx.SourceRecordName)
+        .replace(/\{Date\}/g, () => dateVal)
+        .replace(/\{User\}/g, () => userVal)
+        .replace(/\{n\}/g, () => counterVal)
+        .trim();
+}
+/**
+ * Implements the 'increment' naming strategy.
+ * Detects trailing versions/integers and bumps them:
+ * - "Project v1" -> "Project v2"
+ * - "Doc 1.0" -> "Doc 1.1"
+ * - "Widget (2)" -> "Widget (3)"
+ * - "Widget" -> "Widget 2"
+ */
+export function IncrementName(name) {
+    // Linear scans instead of anchored lazy regexes, which backtrack polynomially on long digit or whitespace runs.
+    // 1. Parenthesized number at end: "Title (1)" -> "Title (2)"
+    if (name.endsWith(')')) {
+        const [beforeDigits, digits] = splitTrailingDigits(name.slice(0, -1));
+        if (digits && beforeDigits.endsWith('(')) {
+            const prefix = beforeDigits.slice(0, -1).trimEnd();
+            return `${prefix} (${parseInt(digits, 10) + 1})`;
+        }
+    }
+    // 2. Dotted version at end: "Title v1.2" or "Title 1.2" -> "Title 1.3"
+    const [beforeMinor, minor] = splitTrailingDigits(name);
+    if (minor && beforeMinor.endsWith('.')) {
+        const [prefix, major] = splitTrailingDigits(beforeMinor.slice(0, -1));
+        if (major) {
+            return `${prefix}${major}.${parseInt(minor, 10) + 1}`;
+        }
+    }
+    // 3. Trailing integer with or without 'v'/'V' after a word boundary: "Title v1" -> "Title v2", "Title 5" -> "Title 6"
+    if (minor) {
+        const withoutV = /[vV]$/.test(beforeMinor) ? beforeMinor.slice(0, -1) : beforeMinor;
+        if (withoutV === '' || !/\w$/.test(withoutV)) {
+            return `${beforeMinor}${parseInt(minor, 10) + 1}`;
+        }
+    }
+    // 4. No number: append " 2"
+    return `${name} 2`;
+}
+/** Splits a string into [everything before the trailing digit run, the trailing digits]. */
+function splitTrailingDigits(value) {
+    let i = value.length;
+    while (i > 0 && value.charCodeAt(i - 1) >= 48 && value.charCodeAt(i - 1) <= 57) {
+        i--;
+    }
+    return [value.slice(0, i), value.slice(i)];
+}
+/** Most candidates tried before giving up; a column this crowded needs a name from the user. */
+const MAX_NAME_ATTEMPTS = 1000;
+/**
+ * `head + keep`, shortening `head` (never `keep`, which carries the counter) to fit `maxLength`.
+ * Null when `keep` alone doesn't fit.
+ */
+function fitKeeping(head, keep, maxLength) {
+    if (!maxLength || maxLength <= 0 || head.length + keep.length <= maxLength)
+        return head + keep;
+    const room = maxLength - keep.length;
+    if (room < 0)
+        return null;
+    return head.slice(0, room).trimEnd() + keep;
+}
+/**
+ * The next name not in `existingNames`, or null when none can be found: the column is too short
+ * for a distinct name, or every candidate within MAX_NAME_ATTEMPTS is taken. Comparison is
+ * case-insensitive, like SQL Server's default collation. The source name itself is never returned
+ * by the renaming strategies ('none' and 'prompt' leave the name to the caller).
+ */
+export function TryFindNextAvailableName(sourceName, existingNames, options) {
+    const strategy = options?.Strategy || 'suffix';
+    if (strategy === 'none' || strategy === 'prompt')
+        return sourceName;
+    const lowered = new Set([...existingNames].map((n) => n.toLowerCase()));
+    const seen = new Set([sourceName.toLowerCase()]);
+    for (const candidate of nameCandidates(sourceName, options)) {
+        // An increment that no longer fits ends the search; a suffix candidate that doesn't fit is skipped.
+        if (candidate === null) {
+            if (strategy === 'increment')
+                return null;
+            continue;
+        }
+        const key = candidate.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        if (!lowered.has(key))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Every name the renaming strategies try, in order, up to MAX_NAME_ATTEMPTS; null for one that
+ * can't fit `MaxLength`. Candidates may repeat (a short column cuts several to the same text).
+ */
+function* nameCandidates(sourceName, options) {
+    const strategy = options?.Strategy || 'suffix';
+    const maxLength = options?.MaxLength;
+    if (strategy === 'increment') {
+        // Fit each step before checking it, keeping the trailing counter whole.
+        let next = sourceName;
+        for (let i = 0; i < MAX_NAME_ATTEMPTS; i++) {
+            next = IncrementName(next);
+            const closing = next.endsWith(')') ? ')' : '';
+            const [before, digits] = splitTrailingDigits(closing ? next.slice(0, -1) : next);
+            const marker = /\s?[(vV]?$/.exec(before)?.[0] ?? '';
+            const candidate = fitKeeping(before.slice(0, before.length - marker.length), marker + digits + closing, maxLength);
+            yield candidate;
+            if (candidate === null)
+                return;
+        }
+        return;
+    }
+    // 'suffix': the template, then " (n)" (or {n} in the template) until a name is free.
+    const template = options?.Template || 'Copy of {Name}';
+    const ctx = { SourceRecordName: sourceName, DateStr: options?.Context?.DateStr, UserName: options?.Context?.UserName };
+    const hasCounter = template.includes('{n}');
+    const candidateFor = (n) => {
+        const counter = hasCounter ? String(n) : n === 1 ? '' : ` (${n})`;
+        const render = (name) => RenderNameTemplate(template, { ...ctx, SourceRecordName: name, Counter: n });
+        const withCounter = (name) => (hasCounter ? render(name) : render(name) + counter);
+        const full = withCounter(sourceName);
+        if (!maxLength || maxLength <= 0 || full.length <= maxLength)
+            return full;
+        // Shorten the name first...
+        const room = sourceName.length - (full.length - maxLength);
+        if (room > 0) {
+            const shortened = withCounter(sourceName.slice(0, room).trimEnd());
+            // A template without {Name} doesn't get shorter with the name: fall through to trimming its text.
+            if (shortened.length <= maxLength)
+                return shortened;
+        }
+        // ...then the template's own text, keeping the counter.
+        const bare = hasCounter ? RenderNameTemplate(template, { ...ctx, SourceRecordName: '', Counter: undefined }) : render('');
+        return fitKeeping(bare, hasCounter ? String(n) : counter, maxLength);
+    };
+    for (let n = 1; n <= MAX_NAME_ATTEMPTS; n++)
+        yield candidateFor(n);
+}
+/**
+ * Finds the next available name for `sourceName`; see {@link TryFindNextAvailableName}. Returns the
+ * source name unchanged when no distinct name can be found.
+ */
+export function FindNextAvailableName(sourceName, existingNames, options) {
+    return TryFindNextAvailableName(sourceName, existingNames, options) ?? sourceName;
+}
+//# sourceMappingURL=NameTemplate.js.map

package/dist/NameTemplate.js.map

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