@memberjunction/metadata-sync 6.2.0-edge.4 → 6.2.0-edge.6

package/dist/lib/env-reference.js

@@ -0,0 +1,241 @@
+/**
+ * @fileoverview Parsing and checks for `@env:` references in metadata files.
+ * @module env-reference
+ */
+import { METADATA_KEYWORDS } from '../constants/metadata-keywords.js';
+import { MIN_MASKED_VALUE_LENGTH } from './env-display.js';
+/** Matches `@env:VARIABLE`, with an optional `?optional` modifier. */
+export const ENV_REFERENCE_PATTERN = /^@env:([^?]+)(\?optional)?$/;
+/**
+ * Parses an `@env:` reference.
+ * @returns The parsed reference, or null when the value is not a valid `@env:` reference
+ */
+export function ParseEnvReference(value) {
+    if (typeof value !== 'string' || !value.startsWith(METADATA_KEYWORDS.ENV)) {
+        return null;
+    }
+    const match = value.match(ENV_REFERENCE_PATTERN);
+    if (!match) {
+        return null;
+    }
+    return { VariableName: match[1], Optional: match[2] !== undefined };
+}
+/** True when an environment value is `true` or `1`, ignoring case and surrounding spaces. */
+export function IsEnvFlagTrue(value) {
+    const normalized = value?.trim().toLowerCase();
+    return normalized === 'true' || normalized === '1';
+}
+/** Thrown when an `@env:VAR?optional` reference names a variable that is not set. */
+export class OptionalEnvMissingError extends Error {
+    constructor(variableName) {
+        super(`Optional environment variable not set: ${variableName}`);
+        this.name = 'OptionalEnvMissingError';
+        this.VariableName = variableName;
+    }
+}
+/** Thrown when a non-optional `@env:` reference names a variable that is not set. Holds names only. */
+export class EnvVariableNotSetError extends Error {
+    constructor(variableName, field, entityName) {
+        super(`Environment variable not found: ${variableName}`);
+        this.name = 'EnvVariableNotSetError';
+        this.VariableName = variableName;
+        this.Field = field;
+        this.EntityName = entityName;
+    }
+    /** The same error for the given field (and entity, when given). */
+    ForField(field, entityName) {
+        return new EnvVariableNotSetError(this.VariableName, field, entityName ?? this.EntityName);
+    }
+    /** The same error inside a composition path, such as `collections.Lines[0]`; an entity already named is kept. */
+    Within(compositionPath, entityName) {
+        const field = this.Field ? `${compositionPath}.${this.Field}` : compositionPath;
+        return new EnvVariableNotSetError(this.VariableName, field, this.EntityName ?? entityName);
+    }
+}
+/** The warning push gives when it leaves out a field whose optional variable is not set. */
+export function OptionalEnvSkipMessage(entityName, fieldName, variableName) {
+    return `${entityName}.${fieldName} was not pushed: optional variable ${variableName} is not set`;
+}
+/**
+ * Decides whether pull keeps an existing `@env:` reference instead of the database value.
+ * The result never contains the variable's value.
+ * @returns The reference to keep, or null when the existing value is not a valid `@env:` reference
+ */
+export function KeepEnvReference(existingValue, databaseValue, env = process.env) {
+    if (typeof existingValue !== 'string') {
+        return null;
+    }
+    const reference = ParseEnvReference(existingValue);
+    if (!reference) {
+        return null;
+    }
+    const envValue = env[reference.VariableName];
+    let check = 'Unset';
+    if (envValue !== undefined) {
+        check = comparable(envValue) === comparable(databaseValue) ? 'Match' : 'Drift';
+    }
+    return { Reference: existingValue, VariableName: reference.VariableName, Check: check };
+}
+function comparable(value) {
+    return value === null || value === undefined ? null : String(value).trim();
+}
+/** True for a plain object or an array. */
+export function IsJsonContainer(value) {
+    if (Array.isArray(value)) {
+        return true;
+    }
+    return value !== null && typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype;
+}
+/** True when an object or array holds a valid `@env:` string at any depth. */
+export function HasNestedEnvReference(value) {
+    return IsJsonContainer(value) && containsEnvLeaf(value);
+}
+function containsEnvLeaf(value) {
+    if (typeof value === 'string') {
+        return ParseEnvReference(value) !== null;
+    }
+    if (Array.isArray(value)) {
+        return value.some(containsEnvLeaf);
+    }
+    if (IsJsonContainer(value)) {
+        return Object.values(value).some(containsEnvLeaf);
+    }
+    return false;
+}
+/**
+ * Keeps `@env:` references inside a JSON field. The database value decides the structure and every
+ * other leaf. A reference is put back only at a path that also exists in the database value; arrays
+ * match by index. When the merged JSON would still hold the value (6 or more characters) of a variable
+ * that the existing value references, the existing value is kept as is.
+ * @returns null when the existing value is not an object or array, or holds no valid `@env:` string
+ */
+export function KeepNestedEnvReferences(existingValue, databaseValue, env = process.env) {
+    if (!IsJsonContainer(existingValue) || !containsEnvLeaf(existingValue)) {
+        return null;
+    }
+    const parsed = parseJsonContainer(databaseValue);
+    if (parsed === null) {
+        return { Value: structuredClone(existingValue), Kept: [], KeptFileValue: true, LeftValueVariables: [] };
+    }
+    const value = structuredClone(parsed);
+    const kept = [];
+    putBackReferences(existingValue, value, '', kept, env);
+    const leftValueVariables = findLeftValueVariables(existingValue, value, env);
+    if (leftValueVariables.length > 0) {
+        return {
+            Value: structuredClone(existingValue),
+            Kept: [],
+            KeptFileValue: true,
+            LeftValueVariables: leftValueVariables,
+        };
+    }
+    return { Value: value, Kept: kept, KeptFileValue: false, LeftValueVariables: [] };
+}
+/** Sorted names of the referenced variables whose value is still in the merged JSON. */
+function findLeftValueVariables(existing, merged, env) {
+    const mergedText = JSON.stringify(merged);
+    return [...collectEnvVariableNames(existing, new Set())]
+        .filter((name) => holdsEnvValue(mergedText, env[name]))
+        .sort();
+}
+function collectEnvVariableNames(value, names) {
+    if (typeof value === 'string') {
+        const reference = ParseEnvReference(value);
+        if (reference) {
+            names.add(reference.VariableName);
+        }
+    }
+    else if (Array.isArray(value)) {
+        value.forEach((item) => collectEnvVariableNames(item, names));
+    }
+    else if (IsJsonContainer(value)) {
+        Object.values(value).forEach((item) => collectEnvVariableNames(item, names));
+    }
+    return names;
+}
+/** Most JSON-escape levels the left-over check looks for (a JSON string inside a JSON string, and so on). */
+const MAX_ESCAPE_LEVELS = 4;
+/** True when the text holds the trimmed value, plain or JSON-escaped one or more times. */
+function holdsEnvValue(text, envValue) {
+    const trimmed = envValue?.trim();
+    if (!trimmed || trimmed.length < MIN_MASKED_VALUE_LENGTH) {
+        return false;
+    }
+    let form = trimmed;
+    for (let level = 0; level <= MAX_ESCAPE_LEVELS; level++) {
+        if (text.includes(form)) {
+            return true;
+        }
+        const escaped = JSON.stringify(form).slice(1, -1);
+        if (escaped === form) {
+            return false;
+        }
+        form = escaped;
+    }
+    return false;
+}
+function parseJsonContainer(value) {
+    if (IsJsonContainer(value)) {
+        return value;
+    }
+    if (typeof value !== 'string') {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(value);
+        return IsJsonContainer(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function putBackReferences(existing, target, path, kept, env) {
+    if (Array.isArray(existing)) {
+        if (!Array.isArray(target)) {
+            return;
+        }
+        const count = Math.min(existing.length, target.length);
+        for (let i = 0; i < count; i++) {
+            const reference = keepLeaf(existing[i], target[i], `${path}[${i}]`, kept, env);
+            if (reference !== null) {
+                target[i] = reference;
+            }
+        }
+        return;
+    }
+    if (Array.isArray(target)) {
+        return;
+    }
+    for (const [key, item] of Object.entries(existing)) {
+        if (!Object.prototype.hasOwnProperty.call(target, key)) {
+            continue;
+        }
+        const reference = keepLeaf(item, target[key], appendKey(path, key), kept, env);
+        if (reference !== null) {
+            target[key] = reference;
+        }
+    }
+}
+/** The reference to put at this path, or null. Walks into nested objects and arrays. */
+function keepLeaf(existingItem, targetItem, path, kept, env) {
+    if (typeof existingItem === 'string') {
+        const comparable = IsJsonContainer(targetItem) ? JSON.stringify(targetItem) : targetItem;
+        const result = KeepEnvReference(existingItem, comparable, env);
+        if (!result) {
+            return null;
+        }
+        kept.push({ Path: path, Reference: result.Reference, VariableName: result.VariableName, Check: result.Check });
+        return result.Reference;
+    }
+    if (IsJsonContainer(existingItem) && IsJsonContainer(targetItem)) {
+        putBackReferences(existingItem, targetItem, path, kept, env);
+    }
+    return null;
+}
+function appendKey(path, key) {
+    if (/^[A-Za-z_$][\w$]*$/.test(key)) {
+        return path ? `${path}.${key}` : key;
+    }
+    return `${path}[${JSON.stringify(key)}]`;
+}
+//# sourceMappingURL=env-reference.js.map

package/dist/lib/env-reference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-reference.js","sourceRoot":"","sources":["../../src/lib/env-reference.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAExD,sEAAsE;AACtE,MAAM,CAAC,MAAM,qBAAqB,GAAG,6BAA6B,CAAC;AAUnE;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,iBAAiB,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1E,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC;IACjD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,EAAE,YAAY,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS,EAAE,CAAC;AACtE,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,aAAa,CAAC,KAAyB;IACrD,MAAM,UAAU,GAAG,KAAK,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC/C,OAAO,UAAU,KAAK,MAAM,IAAI,UAAU,KAAK,GAAG,CAAC;AACrD,CAAC;AAED,qFAAqF;AACrF,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAGhD,YAAY,YAAoB;QAC9B,KAAK,CAAC,0CAA0C,YAAY,EAAE,CAAC,CAAC;QAChE,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;QACtC,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACnC,CAAC;CACF;AAED,uGAAuG;AACvG,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAU/C,YAAY,YAAoB,EAAE,KAAc,EAAE,UAAmB;QACnE,KAAK,CAAC,mCAAmC,YAAY,EAAE,CAAC,CAAC;QACzD,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;IAED,mEAAmE;IACnE,QAAQ,CAAC,KAAa,EAAE,UAAmB;QACzC,OAAO,IAAI,sBAAsB,CAAC,IAAI,CAAC,YAAY,EAAE,KAAK,EAAE,UAAU,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC;IAC7F,CAAC;IAED,iHAAiH;IACjH,MAAM,CAAC,eAAuB,EAAE,UAA8B;QAC5D,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,eAAe,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,eAAe,CAAC;QAChF,OAAO,IAAI,sBAAsB,CAAC,IAAI,CAAC,YAAY,EAAE,KAAK,EAAE,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC,CAAC;IAC7F,CAAC;CACF;AAED,4FAA4F;AAC5F,MAAM,UAAU,sBAAsB,CAAC,UAAkB,EAAE,SAAiB,EAAE,YAAoB;IAChG,OAAO,GAAG,UAAU,IAAI,SAAS,sCAAsC,YAAY,aAAa,CAAC;AACnG,CAAC;AAaD;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAC9B,aAAsB,EACtB,aAAsB,EACtB,MAAyB,OAAO,CAAC,GAAG;IAEpC,IAAI,OAAO,aAAa,KAAK,QAAQ,EAAE,CAAC;QACtC,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,SAAS,GAAG,iBAAiB,CAAC,aAAa,CAAC,CAAC;IACnD,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,QAAQ,GAAG,GAAG,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;IAC7C,IAAI,KAAK,GAAsB,OAAO,CAAC;IACvC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,KAAK,GAAG,UAAU,CAAC,QAAQ,CAAC,KAAK,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;IACjF,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,YAAY,EAAE,SAAS,CAAC,YAAY,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC1F,CAAC;AAED,SAAS,UAAU,CAAC,KAAc;IAChC,OAAO,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;AAC7E,CAAC;AAQD,2CAA2C;AAC3C,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,KAAK,MAAM,CAAC,SAAS,CAAC;AAC1G,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,OAAO,eAAe,CAAC,KAAK,CAAC,IAAI,eAAe,CAAC,KAAK,CAAC,CAAC;AAC1D,CAAC;AAED,SAAS,eAAe,CAAC,KAAc;IACrC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,iBAAiB,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC;IAC3C,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IACrC,CAAC;IACD,IAAI,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AA6BD;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CACrC,aAAsB,EACtB,aAAsB,EACtB,MAAyB,OAAO,CAAC,GAAG;IAEpC,IAAI,CAAC,eAAe,CAAC,aAAa,CAAC,IAAI,CAAC,eAAe,CAAC,aAAa,CAAC,EAAE,CAAC;QACvE,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,MAAM,GAAG,kBAAkB,CAAC,aAAa,CAAC,CAAC;IACjD,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,OAAO,EAAE,KAAK,EAAE,eAAe,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,kBAAkB,EAAE,EAAE,EAAE,CAAC;IAC1G,CAAC;IACD,MAAM,KAAK,GAAkB,eAAe,CAAC,MAAM,CAAC,CAAC;IACrD,MAAM,IAAI,GAA6B,EAAE,CAAC;IAC1C,iBAAiB,CAAC,aAAa,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;IACvD,MAAM,kBAAkB,GAAG,sBAAsB,CAAC,aAAa,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;IAC7E,IAAI,kBAAkB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClC,OAAO;YACL,KAAK,EAAE,eAAe,CAAC,aAAa,CAAC;YACrC,IAAI,EAAE,EAAE;YACR,aAAa,EAAE,IAAI;YACnB,kBAAkB,EAAE,kBAAkB;SACvC,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,kBAAkB,EAAE,EAAE,EAAE,CAAC;AACpF,CAAC;AAED,wFAAwF;AACxF,SAAS,sBAAsB,CAAC,QAAuB,EAAE,MAAqB,EAAE,GAAsB;IACpG,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC1C,OAAO,CAAC,GAAG,uBAAuB,CAAC,QAAQ,EAAE,IAAI,GAAG,EAAU,CAAC,CAAC;SAC7D,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,aAAa,CAAC,UAAU,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;SACtD,IAAI,EAAE,CAAC;AACZ,CAAC;AAED,SAAS,uBAAuB,CAAC,KAAgB,EAAE,KAAkB;IACnE,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,SAAS,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;QAC3C,IAAI,SAAS,EAAE,CAAC;YACd,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;SAAM,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAChC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,uBAAuB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;IAChE,CAAC;SAAM,IAAI,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;QAClC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,uBAAuB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;IAC/E,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,6GAA6G;AAC7G,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAE5B,2FAA2F;AAC3F,SAAS,aAAa,CAAC,IAAY,EAAE,QAA4B;IAC/D,MAAM,OAAO,GAAG,QAAQ,EAAE,IAAI,EAAE,CAAC;IACjC,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,uBAAuB,EAAE,CAAC;QACzD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,IAAI,GAAG,OAAO,CAAC;IACnB,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,IAAI,iBAAiB,EAAE,KAAK,EAAE,EAAE,CAAC;QACxD,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QAClD,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,GAAG,OAAO,CAAC;IACjB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAc;IACxC,IAAI,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC;QACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC1C,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,iBAAiB,CACxB,QAAuB,EACvB,MAAqB,EACrB,IAAY,EACZ,IAA8B,EAC9B,GAAsB;IAEtB,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,OAAO;QACT,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QACvD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;YAC/B,MAAM,SAAS,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;YAC/E,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;gBACvB,MAAM,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;YACxB,CAAC;QACH,CAAC;QACD,OAAO;IACT,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,OAAO;IACT,CAAC;IACD,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QACnD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;YACvD,SAAS;QACX,CAAC;QACD,MAAM,SAAS,GAAG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,SAAS,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;QAC/E,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;YACvB,MAAM,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;QAC1B,CAAC;IACH,CAAC;AACH,CAAC;AAED,wFAAwF;AACxF,SAAS,QAAQ,CACf,YAAuB,EACvB,UAAqB,EACrB,IAAY,EACZ,IAA8B,EAC9B,GAAsB;IAEtB,IAAI,OAAO,YAAY,KAAK,QAAQ,EAAE,CAAC;QACrC,MAAM,UAAU,GAAG,eAAe,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;QACzF,MAAM,MAAM,GAAG,gBAAgB,CAAC,YAAY,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC;QAC/D,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,YAAY,EAAE,MAAM,CAAC,YAAY,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;QAC/G,OAAO,MAAM,CAAC,SAAS,CAAC;IAC1B,CAAC;IACD,IAAI,eAAe,CAAC,YAAY,CAAC,IAAI,eAAe,CAAC,UAAU,CAAC,EAAE,CAAC;QACjE,iBAAiB,CAAC,YAAY,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,SAAS,CAAC,IAAY,EAAE,GAAW;IAC1C,IAAI,oBAAoB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACnC,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;IACvC,CAAC;IACD,OAAO,GAAG,IAAI,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC;AAC3C,CAAC"}

package/dist/lib/env-sql-redactor.d.ts

@@ -0,0 +1,74 @@
+import type { BaseEntity } from '@memberjunction/core';
+import type { SyncEngine } from './sync-engine.js';
+/** Replaces registered SET lines and gives names-only warnings for one push. */
+export declare class EnvSqlRedactor {
+    private readonly variables;
+    private readonly env;
+    /** Registrations by save-call hash; `ANY_SAVE_CALL_SUFFIX` holds those registered without a hash. */
+    private readonly fieldsByHash;
+    private readonly primaryKeys;
+    private transformFailed;
+    /** `variables` is read when `Warnings` runs, so a set that grows during the run can be passed. */
+    constructor(variables: ReadonlySet<string>, env?: NodeJS.ProcessEnv);
+    /**
+     * Registers a field whose value is in a save statement. With `saveCallHash` (the 12-hex
+     * `GenericDatabaseProvider.SaveCallVariableHash` of the record), only the SET line of that save
+     * call is replaced. Without it, the SET line of any save call with the same code name and literal
+     * is replaced. A null or undefined value is not registered, because no SET line is written for it.
+     * A registration stays for the whole push.
+     */
+    Register(entityName: string, fieldName: string, codeName: string, value: unknown, variableNames: ReadonlySet<string>, saveCallHash?: string): void;
+    /** Registers an env-sourced primary key field. Its value stays in the log, so it gives a warning. */
+    RegisterPrimaryKey(entityName: string, fieldName: string, variableNames: ReadonlySet<string>): void;
+    /**
+     * Registers the env-sourced fields that the save statement of `entity` holds. Each field is
+     * registered at the IS-A level whose table holds it, with that level's save-call hash. A level's
+     * statement holds every field when `fullRow` (a create or alwaysPush) or when its entity has no
+     * generated update procedure (the full save SQL is logged); else only the changed fields.
+     * Key fields give a warning. `envFields` keys are matched without regard to case. Call it right
+     * before the save, so the hash uses the key values the provider hashes.
+     */
+    RegisterEntityFields(entity: BaseEntity, envFields: ReadonlyMap<string, ReadonlySet<string>> | undefined, fullRow: boolean): void;
+    /**
+     * The `SqlLoggingOptions.TransformStatement` function. It can run many times on the same text and
+     * on text that is never written. It only marks fields as matched and never throws; on an
+     * unexpected error it returns a comment in place of the statement.
+     */
+    readonly Transform: (sql: string) => string;
+    /** Names-only warnings for the SQL log at `sqlLogPath`. Reads the written log; never throws. */
+    Warnings(sqlLogPath: string): string[];
+    private fieldsForHash;
+    /** The registrations that can match the statement: those of each suffix in it, and those without a hash. */
+    private candidateFields;
+    private replaceSetLines;
+    private unmatchedFieldWarnings;
+    private primaryKeyWarnings;
+    /**
+     * For each resolved variable other than a key variable: a warning when its value is in the
+     * written log, or when it is not set now and so cannot be checked.
+     */
+    private variableValueWarnings;
+}
+/** The sync engine members an `EnvSqlLog` uses. */
+type EnvSqlLogEngine = Pick<SyncEngine, 'BeforeLookupCreateSave' | 'ResolvedEnvVariables'>;
+/**
+ * The redactor of one open SQL log, with the `SyncEngine.BeforeLookupCreateSave` hook that registers
+ * each record a `?create` lookup creates (with the full row, because a create writes every field).
+ */
+export declare class EnvSqlLog {
+    readonly Redactor: EnvSqlRedactor;
+    private readonly engine;
+    private readonly hook;
+    /** Creates the redactor over the engine's resolved variables and sets the engine's hook. */
+    constructor(engine: EnvSqlLogEngine);
+    /** Clears the engine's hook when it is still this log's hook. */
+    Close(): void;
+}
+/**
+ * Adds a field that was left out because its `?optional` variable is not set. The SQL log then
+ * leaves the field's SET line out by name, as for an env-sourced field: a full-row save would
+ * otherwise write the field's database value.
+ */
+export declare function AddSkippedOptionalEnvField(envFields: Map<string, Set<string>> | undefined, fieldName: string, variableName: string): void;
+export {};
+//# sourceMappingURL=env-sql-redactor.d.ts.map

package/dist/lib/env-sql-redactor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-sql-redactor.d.ts","sourceRoot":"","sources":["../../src/lib/env-sql-redactor.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAIvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAehD,gFAAgF;AAChF,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsB;IAChD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAoB;IACxC,qGAAqG;IACrG,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAiD;IAC9E,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAyC;IACrE,OAAO,CAAC,eAAe,CAAS;IAEhC,kGAAkG;gBACtF,SAAS,EAAE,WAAW,CAAC,MAAM,CAAC,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB;IAKhF;;;;;;OAMG;IACH,QAAQ,CACN,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,OAAO,EACd,aAAa,EAAE,WAAW,CAAC,MAAM,CAAC,EAClC,YAAY,CAAC,EAAE,MAAM,GACpB,IAAI;IAoBP,qGAAqG;IACrG,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,IAAI;IAUnG;;;;;;;OAOG;IACH,oBAAoB,CAClB,MAAM,EAAE,UAAU,EAClB,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,EAC/D,OAAO,EAAE,OAAO,GACf,IAAI;IAuBP;;;;OAIG;IACH,QAAQ,CAAC,SAAS,GAAI,KAAK,MAAM,KAAG,MAAM,CAOxC;IAEF,gGAAgG;IAChG,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE;IAYtC,OAAO,CAAC,aAAa;IASrB,4GAA4G;IAC5G,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,eAAe;IAgBvB,OAAO,CAAC,sBAAsB;IAU9B,OAAO,CAAC,kBAAkB;IAM1B;;;OAGG;IACH,OAAO,CAAC,qBAAqB;CAiB9B;AAqBD,mDAAmD;AACnD,KAAK,eAAe,GAAG,IAAI,CAAC,UAAU,EAAE,wBAAwB,GAAG,sBAAsB,CAAC,CAAC;AAE3F;;;GAGG;AACH,qBAAa,SAAS;IACpB,SAAgB,QAAQ,EAAE,cAAc,CAAC;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAoD;IAEzE,4FAA4F;gBAChF,MAAM,EAAE,eAAe;IAOnC,iEAAiE;IACjE,KAAK,IAAI,IAAI;CAKd;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,EAC/C,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,GACnB,IAAI,CAON"}

package/dist/lib/env-sql-redactor.js

@@ -0,0 +1,232 @@
+/**
+ * @fileoverview Leaves the values of env-sourced fields out of the push SQL log.
+ *
+ * SQL Server saves set each parameter with one line: `SET @<CodeName>_<12 hex>[_n] = <literal>`.
+ * For a registered field, that line is replaced with a comment. The variable is then NULL in the
+ * recorded statement, so a replayed update keeps the target's value. A primary key cannot be left
+ * out; it gives a warning. After the run, the written log is searched for the values of the
+ * resolved variables. All messages name variables, never values.
+ * @module env-sql-redactor
+ */
+import fs from 'fs';
+import { GenericDatabaseProvider } from '@memberjunction/generic-database-provider';
+import { EnvDisplayMask } from './env-display.js';
+import { ANY_SAVE_CALL_SUFFIX, OwningLevel, SaveCallHashesIn, SetLinePattern, SqlLiteralsOf } from './sql-set-line.js';
+/** Replaces registered SET lines and gives names-only warnings for one push. */
+export class EnvSqlRedactor {
+    /** `variables` is read when `Warnings` runs, so a set that grows during the run can be passed. */
+    constructor(variables, env = process.env) {
+        /** Registrations by save-call hash; `ANY_SAVE_CALL_SUFFIX` holds those registered without a hash. */
+        this.fieldsByHash = new Map();
+        this.primaryKeys = new Map();
+        this.transformFailed = false;
+        /**
+         * The `SqlLoggingOptions.TransformStatement` function. It can run many times on the same text and
+         * on text that is never written. It only marks fields as matched and never throws; on an
+         * unexpected error it returns a comment in place of the statement.
+         */
+        this.Transform = (sql) => {
+            try {
+                return this.replaceSetLines(sql);
+            }
+            catch {
+                this.transformFailed = true;
+                return '-- Statement not logged: env values could not be left out';
+            }
+        };
+        this.variables = variables;
+        this.env = env;
+    }
+    /**
+     * Registers a field whose value is in a save statement. With `saveCallHash` (the 12-hex
+     * `GenericDatabaseProvider.SaveCallVariableHash` of the record), only the SET line of that save
+     * call is replaced. Without it, the SET line of any save call with the same code name and literal
+     * is replaced. A null or undefined value is not registered, because no SET line is written for it.
+     * A registration stays for the whole push.
+     */
+    Register(entityName, fieldName, codeName, value, variableNames, saveCallHash) {
+        const literals = SqlLiteralsOf(value);
+        if (literals.length === 0) {
+            return;
+        }
+        const hash = saveCallHash?.toLowerCase() ?? ANY_SAVE_CALL_SUFFIX;
+        const fields = this.fieldsForHash(hash);
+        const key = [entityName, fieldName, codeName, ...literals].join('\u0000');
+        if (fields.has(key)) {
+            return;
+        }
+        fields.set(key, {
+            EntityName: entityName,
+            FieldName: fieldName,
+            Sources: sourcesOf(variableNames),
+            Pattern: SetLinePattern(codeName, hash, literals),
+            Matched: false,
+        });
+    }
+    /** Registers an env-sourced primary key field. Its value stays in the log, so it gives a warning. */
+    RegisterPrimaryKey(entityName, fieldName, variableNames) {
+        const field = `${entityName}.${fieldName}`;
+        const existing = this.primaryKeys.get(field);
+        if (existing) {
+            variableNames.forEach((name) => existing.Variables.add(name));
+        }
+        else {
+            this.primaryKeys.set(field, { Field: field, Variables: new Set(variableNames) });
+        }
+    }
+    /**
+     * Registers the env-sourced fields that the save statement of `entity` holds. Each field is
+     * registered at the IS-A level whose table holds it, with that level's save-call hash. A level's
+     * statement holds every field when `fullRow` (a create or alwaysPush) or when its entity has no
+     * generated update procedure (the full save SQL is logged); else only the changed fields.
+     * Key fields give a warning. `envFields` keys are matched without regard to case. Call it right
+     * before the save, so the hash uses the key values the provider hashes.
+     */
+    RegisterEntityFields(entity, envFields, fullRow) {
+        if (!envFields || envFields.size === 0) {
+            return;
+        }
+        const keyNames = new Set(entity.EntityInfo.PrimaryKeys.map((pk) => pk.Name));
+        for (const [key, variables] of envFields) {
+            const fieldName = entity.GetFieldByName(key)?.Name ?? key;
+            if (keyNames.has(fieldName)) {
+                this.RegisterPrimaryKey(entity.EntityInfo.Name, fieldName, variables);
+                continue;
+            }
+            const level = OwningLevel(entity, fieldName);
+            const field = level.GetFieldByName(fieldName);
+            const levelInfo = level.EntityInfo;
+            const holdsField = fullRow || !levelInfo.spUpdateGenerated || fieldName in level.GetChangesSinceLastSave();
+            if (field && holdsField) {
+                const keyValues = level.PrimaryKey?.KeyValuePairs?.map((pair) => pair.Value) ?? [];
+                const saveCallHash = GenericDatabaseProvider.SaveCallVariableHash(levelInfo.SchemaName, levelInfo.BaseTable, keyValues);
+                this.Register(levelInfo.Name, fieldName, field.EntityFieldInfo.CodeName, level.Get(fieldName), variables, saveCallHash);
+            }
+        }
+    }
+    /** Names-only warnings for the SQL log at `sqlLogPath`. Reads the written log; never throws. */
+    Warnings(sqlLogPath) {
+        const failure = this.transformFailed
+            ? [`SQL log ${sqlLogPath}: env values could not be left out of a statement. Check the log before you share it.`]
+            : [];
+        return [
+            ...failure,
+            ...this.unmatchedFieldWarnings(sqlLogPath),
+            ...this.primaryKeyWarnings(sqlLogPath),
+            ...this.variableValueWarnings(sqlLogPath),
+        ];
+    }
+    fieldsForHash(hash) {
+        let fields = this.fieldsByHash.get(hash);
+        if (!fields) {
+            fields = new Map();
+            this.fieldsByHash.set(hash, fields);
+        }
+        return fields;
+    }
+    /** The registrations that can match the statement: those of each suffix in it, and those without a hash. */
+    candidateFields(sql) {
+        const hashes = SaveCallHashesIn(sql);
+        const candidates = [];
+        for (const hash of hashes) {
+            this.fieldsByHash.get(hash)?.forEach((field) => candidates.push(field));
+        }
+        return candidates;
+    }
+    replaceSetLines(sql) {
+        if (this.fieldsByHash.size === 0) {
+            return sql;
+        }
+        let result = sql;
+        for (const field of this.candidateFields(sql)) {
+            const comment = `-- ${field.EntityName}.${field.FieldName}: not recorded, value comes from ${field.Sources}`;
+            const next = result.replace(field.Pattern, (_line, indent) => `${indent}${comment}`);
+            if (next !== result) {
+                field.Matched = true;
+                result = next;
+            }
+        }
+        return result;
+    }
+    unmatchedFieldWarnings(sqlLogPath) {
+        return [...this.fieldsByHash.values()]
+            .flatMap((fields) => [...fields.values()])
+            .filter((field) => !field.Matched)
+            .map((field) => `SQL log ${sqlLogPath}: the line for ${field.EntityName}.${field.FieldName} (from ${field.Sources}) was not found, so its value may be in the log. Check the log before you share it.`);
+    }
+    primaryKeyWarnings(sqlLogPath) {
+        return [...this.primaryKeys.values()].map((key) => `SQL log ${sqlLogPath}: ${key.Field} is a primary key from ${sourcesOf(key.Variables)}. The log holds its value. Check the log before you share it.`);
+    }
+    /**
+     * For each resolved variable other than a key variable: a warning when its value is in the
+     * written log, or when it is not set now and so cannot be checked.
+     */
+    variableValueWarnings(sqlLogPath) {
+        const logText = readLog(sqlLogPath);
+        if (logText === null) {
+            return [`SQL log ${sqlLogPath}: the log could not be read to check for env values. Check the log before you share it.`];
+        }
+        const keyVariables = new Set();
+        this.primaryKeys.forEach((key) => key.Variables.forEach((name) => keyVariables.add(name)));
+        const warnings = [];
+        for (const name of [...this.variables].filter((variable) => !keyVariables.has(variable)).sort()) {
+            if (this.env[name] === undefined) {
+                warnings.push(`SQL log ${sqlLogPath}: @env:${name} is not set now, so the log could not be checked for its value. Check the log before you share it.`);
+            }
+            else if (valueIsInText(name, logText, this.env)) {
+                warnings.push(`SQL log ${sqlLogPath}: the value of @env:${name} appears in the log. Check the log before you share it.`);
+            }
+        }
+        return warnings;
+    }
+}
+/** The log text, or null when the file cannot be read. */
+function readLog(sqlLogPath) {
+    try {
+        return fs.readFileSync(sqlLogPath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/** True when the variable's value is in the text, found with the same forms and length rule as `EnvDisplayMask.MaskText`. */
+function valueIsInText(name, text, env) {
+    return EnvDisplayMask.ForVariables([name], env).MaskText(text) !== text;
+}
+/** `@env:A` or `@env:A, @env:B`, sorted. */
+function sourcesOf(variableNames) {
+    return [...variableNames].sort().map((name) => `@env:${name}`).join(', ');
+}
+/**
+ * The redactor of one open SQL log, with the `SyncEngine.BeforeLookupCreateSave` hook that registers
+ * each record a `?create` lookup creates (with the full row, because a create writes every field).
+ */
+export class EnvSqlLog {
+    /** Creates the redactor over the engine's resolved variables and sets the engine's hook. */
+    constructor(engine) {
+        this.engine = engine;
+        this.Redactor = new EnvSqlRedactor(engine.ResolvedEnvVariables);
+        this.hook = (created, envFields) => this.Redactor.RegisterEntityFields(created, envFields, true);
+        engine.BeforeLookupCreateSave = this.hook;
+    }
+    /** Clears the engine's hook when it is still this log's hook. */
+    Close() {
+        if (this.engine.BeforeLookupCreateSave === this.hook) {
+            this.engine.BeforeLookupCreateSave = null;
+        }
+    }
+}
+/**
+ * Adds a field that was left out because its `?optional` variable is not set. The SQL log then
+ * leaves the field's SET line out by name, as for an env-sourced field: a full-row save would
+ * otherwise write the field's database value.
+ */
+export function AddSkippedOptionalEnvField(envFields, fieldName, variableName) {
+    if (!envFields) {
+        return;
+    }
+    const variables = envFields.get(fieldName) ?? new Set();
+    variables.add(variableName);
+    envFields.set(fieldName, variables);
+}
+//# sourceMappingURL=env-sql-redactor.js.map

package/dist/lib/env-sql-redactor.js.map

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

package/dist/lib/existing-record-index.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview Finds existing file records by a database primary key. An `@env:` key value is
+ * replaced by its variable (trimmed) for the match, and UUID key fields are compared without case.
+ * @module existing-record-index
+ */
+import type { EntityInfo } from '@memberjunction/core';
+import type { RecordData } from './sync-engine.js';
+import { PrimaryKeyValues } from './record-primary-key.js';
+/** A primaryKey field whose `@env:` variable is not set. Never holds a value. */
+export interface UnsetKeyVariable {
+    VariableName: string;
+    Field: string;
+    /** File that holds the record, when known. */
+    FilePath?: string;
+}
+/** One existing file record. */
+export interface ExistingRecordEntry {
+    Record: RecordData;
+    /** File that holds the record, when known. */
+    FilePath?: string;
+    /** True when the file holds an array of records. */
+    InArray?: boolean;
+}
+/** Thrown when a primaryKey `@env:` variable is not set, so pull cannot match the record. */
+export declare class UnsetPrimaryKeyVariableError extends Error {
+    readonly Variables: ReadonlyArray<UnsetKeyVariable>;
+    /** Entity whose key uses the variables. */
+    readonly EntityName: string;
+    /** Entity the user pulls, when it differs from `EntityName`. */
+    readonly PulledEntityName?: string;
+    constructor(entityName: string, variables: ReadonlyArray<UnsetKeyVariable>, pulledEntityName?: string);
+    /** The same error with `filePath` on each variable that names no file, and the entity the user pulls. */
+    InRecordFile(filePath: string | undefined, pulledEntityName: string): UnsetPrimaryKeyVariableError;
+}
+/** Existing file records, found by the database primary key. The first record wins for a repeated key. */
+export declare class ExistingRecordIndex {
+    private readonly uuidFields;
+    private readonly env;
+    private readonly byKey;
+    private readonly unsetVariables;
+    private duplicates;
+    private constructor();
+    /** Indexes the entries. Records without a primaryKey, or with an unset key variable, are not indexed. */
+    static Build(entries: ReadonlyArray<ExistingRecordEntry>, entityInfo: EntityInfo | null | undefined, env?: NodeJS.ProcessEnv): ExistingRecordIndex;
+    /** The lookup string of a record as the file writes it, for `FileWriteBatch` array updates. */
+    static FileLookupOf(record: RecordData): string;
+    /** Key variables that are not set. The records that use them are not indexed. */
+    get UnsetKeyVariables(): ReadonlyArray<UnsetKeyVariable>;
+    /** Number of records whose key repeats an earlier record's key. */
+    get DuplicateCount(): number;
+    /** @throws UnsetPrimaryKeyVariableError when any key variable is not set */
+    ThrowIfUnsetKeyVariables(entityName: string): void;
+    /** The existing entry whose resolved key equals the database key, or undefined. */
+    Find(databaseKey: PrimaryKeyValues): ExistingRecordEntry | undefined;
+    /** The match string of a database key. */
+    MatchKey(databaseKey: PrimaryKeyValues): string;
+    /** The match string of a file record's key, or null when the key is empty or a key variable is not set. */
+    KeyOf(record: RecordData): string | null;
+    private add;
+    /** A file key value as text: the variable (trimmed) for `@env:`, the value otherwise; null when unusable. */
+    private resolve;
+    /** Trimmed, as a fixed-width key is padded; UUID fields lowercased. */
+    private normalize;
+}
+/**
+ * The primary key pull writes: the file's `@env:` value for each field whose variable (trimmed)
+ * equals the database value, with UUID fields compared without case; the database value otherwise.
+ */
+export declare function KeepPrimaryKeyEnvReferences(fileKey: Record<string, unknown> | undefined, databaseKey: Record<string, unknown>, entityInfo: EntityInfo | null | undefined, env?: NodeJS.ProcessEnv): Record<string, unknown>;
+//# sourceMappingURL=existing-record-index.d.ts.map