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

package/dist/lib/env-derived-fields.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview Finds the values of the `@env:` references in an existing record file, so pull can
+ * leave out a read-only field whose database value holds one of them (for example a key path that
+ * the database builds from an env-sourced primary key).
+ * @module env-derived-fields
+ */
+import type { EntityInfo } from '@memberjunction/core';
+import type { RecordData } from './sync-engine.js';
+/** The value of one `@env:` reference in a record file. Never print `Value`. */
+export interface EnvSourcedValue {
+    VariableName: string;
+    Value: string;
+    /** True for a UUID value, which is compared without case. */
+    IgnoreCase: boolean;
+}
+/**
+ * The values of the set variables that the record file uses in `primaryKey` and anywhere in
+ * `fields`. A non-UUID value shorter than 6 characters is left out, as in masking.
+ */
+export declare function EnvSourcedValuesOf(existing: RecordData | undefined, entityInfo: EntityInfo | null | undefined, env?: NodeJS.ProcessEnv): EnvSourcedValue[];
+/** The first env-sourced value that the database value holds, or undefined. */
+export declare function FindEnvSourcedValue(databaseValue: unknown, values: ReadonlyArray<EnvSourcedValue>): EnvSourcedValue | undefined;
+//# sourceMappingURL=env-derived-fields.d.ts.map

package/dist/lib/env-derived-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-derived-fields.d.ts","sourceRoot":"","sources":["../../src/lib/env-derived-fields.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAOhD,gFAAgF;AAChF,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,UAAU,GAAG,SAAS,EAChC,UAAU,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,EACzC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,eAAe,EAAE,CAanB;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,CAAC,eAAe,CAAC,GAAG,eAAe,GAAG,SAAS,CAO/H"}

package/dist/lib/env-derived-fields.js

@@ -0,0 +1,53 @@
+import { MIN_MASKED_VALUE_LENGTH } from './env-display.js';
+import { ParseEnvReference } from './env-reference.js';
+/** A UUID text, in any case. */
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * The values of the set variables that the record file uses in `primaryKey` and anywhere in
+ * `fields`. A non-UUID value shorter than 6 characters is left out, as in masking.
+ */
+export function EnvSourcedValuesOf(existing, entityInfo, env = process.env) {
+    if (!existing) {
+        return [];
+    }
+    const values = [];
+    for (const [keyName, keyValue] of Object.entries(existing.primaryKey ?? {})) {
+        const isUuid = entityInfo?.Fields.find((f) => f.Name.toLowerCase() === keyName.toLowerCase())?.IsUniqueIdentifier === true;
+        addValue(values, keyValue, isUuid, env);
+    }
+    for (const reference of envReferencesIn(existing.fields)) {
+        addValue(values, reference, false, env);
+    }
+    return values;
+}
+/** The first env-sourced value that the database value holds, or undefined. */
+export function FindEnvSourcedValue(databaseValue, values) {
+    if (values.length === 0 || databaseValue === null || databaseValue === undefined) {
+        return undefined;
+    }
+    const text = typeof databaseValue === 'string' ? databaseValue : JSON.stringify(databaseValue);
+    const lowerText = text.toLowerCase();
+    return values.find((value) => (value.IgnoreCase ? lowerText.includes(value.Value.toLowerCase()) : text.includes(value.Value)));
+}
+function addValue(values, reference, isUuid, env) {
+    const parsed = ParseEnvReference(reference);
+    const value = parsed ? env[parsed.VariableName]?.trim() : undefined;
+    if (!parsed || !value || (!isUuid && value.length < MIN_MASKED_VALUE_LENGTH)) {
+        return;
+    }
+    values.push({ VariableName: parsed.VariableName, Value: value, IgnoreCase: isUuid || UUID_PATTERN.test(value) });
+}
+/** Every string in the value, at any depth, that is an `@env:` reference. */
+function envReferencesIn(value) {
+    if (typeof value === 'string') {
+        return ParseEnvReference(value) ? [value] : [];
+    }
+    if (Array.isArray(value)) {
+        return value.flatMap(envReferencesIn);
+    }
+    if (value !== null && typeof value === 'object') {
+        return Object.values(value).flatMap(envReferencesIn);
+    }
+    return [];
+}
+//# sourceMappingURL=env-derived-fields.js.map

package/dist/lib/env-derived-fields.js.map

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

package/dist/lib/env-display.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview Display text for values that come from `@env:`. Push prints these in place of
+ * the values in diffs, change reports, save-failure dumps and error text.
+ * @module env-display
+ */
+/** Shown for the old database value of an env-sourced field. */
+export declare const ENV_HIDDEN_VALUE = "<hidden>";
+/**
+ * Values shorter than this are not searched for in free text, so short values do not match unrelated text.
+ * Display masking, the pull left-over check and the copied-value check all use it.
+ */
+export declare const MIN_MASKED_VALUE_LENGTH = 6;
+/** `<from @env:A>`, or `<from @env:A, @env:B>` for a field that uses more than one variable. */
+export declare function EnvSourceLabel(variableNames: Iterable<string>): string;
+/**
+ * The thrown value as an Error whose message and stack hold no variable value. A value that is not
+ * an Error is wrapped in a new Error with the masked text. Only `message` and `stack` are masked;
+ * `cause` and other properties are left as they are.
+ */
+export declare function MaskedError(thrown: unknown, mask: EnvDisplayMask): Error;
+/** Masks the env-sourced fields of one record in printed text. */
+export declare class EnvDisplayMask {
+    private readonly fields;
+    private readonly env;
+    /** Variables searched for by MaskText that belong to no field. */
+    private textVariables;
+    constructor(fields?: ReadonlyMap<string, ReadonlySet<string>>, env?: NodeJS.ProcessEnv);
+    /** A mask for free text only: MaskText searches for these variables, and no field is env-sourced. */
+    static ForVariables(variableNames: Iterable<string>, env?: NodeJS.ProcessEnv): EnvDisplayMask;
+    /** True when the record has no env-sourced field. */
+    get IsEmpty(): boolean;
+    /** True when the field is env-sourced. The name matches exactly, or else without regard to case. */
+    IsEnvField(fieldName: string): boolean;
+    /** The old value to print: `<hidden>` for an env-sourced field, else the formatted value. */
+    OldValue(fieldName: string, formatted: string): string;
+    /** The new value to print: `<from @env:VAR>` for an env-sourced field, else the formatted value. */
+    NewValue(fieldName: string, formatted: string): string;
+    /**
+     * Replaces each value of this record's variables in free text with its label, without regard to case.
+     * A variable is searched for only when its trimmed value is at least `MIN_MASKED_VALUE_LENGTH` long.
+     * Matches the value as is, trimmed, with doubled single quotes, JSON-escaped once, and JSON-escaped
+     * with doubled single quotes. Every match is found in the original text; matches that overlap become
+     * one label that names all their variables, so no part of any value is left.
+     */
+    MaskText(text: string): string;
+    /** Every match of every form in the text, overlapping matches included. */
+    private findMatches;
+    /** The variables of a field, found by exact name, or else by name without regard to case. */
+    private variablesFor;
+    /** Every searched form of every set variable. */
+    private maskForms;
+    private variableNames;
+}
+//# sourceMappingURL=env-display.d.ts.map

package/dist/lib/env-display.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-display.d.ts","sourceRoot":"","sources":["../../src/lib/env-display.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,gEAAgE;AAChE,eAAO,MAAM,gBAAgB,aAAa,CAAC;AAE3C;;;GAGG;AACH,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,gGAAgG;AAChG,wBAAgB,cAAc,CAAC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,MAAM,CAGtE;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,cAAc,GAAG,KAAK,CAUxE;AAED,kEAAkE;AAClE,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2C;IAClE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAoB;IACxC,kEAAkE;IAClE,OAAO,CAAC,aAAa,CAAkC;gBAE3C,MAAM,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB;IAKnG,qGAAqG;IACrG,MAAM,CAAC,YAAY,CAAC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,cAAc;IAM1G,qDAAqD;IACrD,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,oGAAoG;IACpG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAItC,6FAA6F;IAC7F,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IAItD,oGAAoG;IACpG,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IAKtD;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAW9B,2EAA2E;IAC3E,OAAO,CAAC,WAAW;IAYnB,6FAA6F;IAC7F,OAAO,CAAC,YAAY;IAcpB,iDAAiD;IACjD,OAAO,CAAC,SAAS;IAcjB,OAAO,CAAC,aAAa;CAOtB"}

package/dist/lib/env-display.js

@@ -0,0 +1,156 @@
+/**
+ * @fileoverview Display text for values that come from `@env:`. Push prints these in place of
+ * the values in diffs, change reports, save-failure dumps and error text.
+ * @module env-display
+ */
+/** Shown for the old database value of an env-sourced field. */
+export const ENV_HIDDEN_VALUE = '<hidden>';
+/**
+ * Values shorter than this are not searched for in free text, so short values do not match unrelated text.
+ * Display masking, the pull left-over check and the copied-value check all use it.
+ */
+export const MIN_MASKED_VALUE_LENGTH = 6;
+/** `<from @env:A>`, or `<from @env:A, @env:B>` for a field that uses more than one variable. */
+export function EnvSourceLabel(variableNames) {
+    const names = [...new Set(variableNames)].sort();
+    return `<from ${names.map((name) => `@env:${name}`).join(', ')}>`;
+}
+/**
+ * The thrown value as an Error whose message and stack hold no variable value. A value that is not
+ * an Error is wrapped in a new Error with the masked text. Only `message` and `stack` are masked;
+ * `cause` and other properties are left as they are.
+ */
+export function MaskedError(thrown, mask) {
+    if (!(thrown instanceof Error)) {
+        const text = typeof thrown === 'object' && thrown !== null ? JSON.stringify(thrown) : String(thrown);
+        return new Error(mask.MaskText(text));
+    }
+    thrown.message = mask.MaskText(thrown.message);
+    if (thrown.stack) {
+        thrown.stack = mask.MaskText(thrown.stack);
+    }
+    return thrown;
+}
+/** Masks the env-sourced fields of one record in printed text. */
+export class EnvDisplayMask {
+    constructor(fields, env = process.env) {
+        /** Variables searched for by MaskText that belong to no field. */
+        this.textVariables = new Set();
+        this.fields = fields ?? new Map();
+        this.env = env;
+    }
+    /** A mask for free text only: MaskText searches for these variables, and no field is env-sourced. */
+    static ForVariables(variableNames, env = process.env) {
+        const mask = new EnvDisplayMask(undefined, env);
+        mask.textVariables = new Set(variableNames);
+        return mask;
+    }
+    /** True when the record has no env-sourced field. */
+    get IsEmpty() {
+        return this.fields.size === 0;
+    }
+    /** True when the field is env-sourced. The name matches exactly, or else without regard to case. */
+    IsEnvField(fieldName) {
+        return this.variablesFor(fieldName) !== undefined;
+    }
+    /** The old value to print: `<hidden>` for an env-sourced field, else the formatted value. */
+    OldValue(fieldName, formatted) {
+        return this.IsEnvField(fieldName) ? ENV_HIDDEN_VALUE : formatted;
+    }
+    /** The new value to print: `<from @env:VAR>` for an env-sourced field, else the formatted value. */
+    NewValue(fieldName, formatted) {
+        const variables = this.variablesFor(fieldName);
+        return variables ? EnvSourceLabel(variables) : formatted;
+    }
+    /**
+     * Replaces each value of this record's variables in free text with its label, without regard to case.
+     * A variable is searched for only when its trimmed value is at least `MIN_MASKED_VALUE_LENGTH` long.
+     * Matches the value as is, trimmed, with doubled single quotes, JSON-escaped once, and JSON-escaped
+     * with doubled single quotes. Every match is found in the original text; matches that overlap become
+     * one label that names all their variables, so no part of any value is left.
+     */
+    MaskText(text) {
+        const ranges = mergeRanges(this.findMatches(text));
+        let result = '';
+        let position = 0;
+        for (const range of ranges) {
+            result += text.slice(position, range.Start) + EnvSourceLabel(range.Names);
+            position = range.End;
+        }
+        return result + text.slice(position);
+    }
+    /** Every match of every form in the text, overlapping matches included. */
+    findMatches(text) {
+        const matches = [];
+        for (const { Form, Name } of this.maskForms()) {
+            const pattern = new RegExp(escapeRegExp(Form), 'gi');
+            for (let match = pattern.exec(text); match !== null; match = pattern.exec(text)) {
+                matches.push({ Start: match.index, End: match.index + Form.length, Names: [Name] });
+                pattern.lastIndex = match.index + 1;
+            }
+        }
+        return matches;
+    }
+    /** The variables of a field, found by exact name, or else by name without regard to case. */
+    variablesFor(fieldName) {
+        const exact = this.fields.get(fieldName);
+        if (exact) {
+            return exact;
+        }
+        const lowerName = fieldName.toLowerCase();
+        for (const [name, variables] of this.fields) {
+            if (name.toLowerCase() === lowerName) {
+                return variables;
+            }
+        }
+        return undefined;
+    }
+    /** Every searched form of every set variable. */
+    maskForms() {
+        const forms = [];
+        for (const name of this.variableNames()) {
+            const value = this.env[name];
+            if (value === undefined || value.trim().length < MIN_MASKED_VALUE_LENGTH) {
+                continue;
+            }
+            const jsonForm = JSON.stringify(value).slice(1, -1);
+            const variants = new Set([value, value.trim(), value.replace(/'/g, "''"), jsonForm, jsonForm.replace(/'/g, "''")]);
+            variants.forEach((form) => forms.push({ Form: form, Name: name }));
+        }
+        return forms;
+    }
+    variableNames() {
+        const variables = new Set(this.textVariables);
+        for (const names of this.fields.values()) {
+            names.forEach((name) => variables.add(name));
+        }
+        return variables;
+    }
+}
+/**
+ * Sorts the ranges and joins the ones that overlap. A range inside another adds no name, so a value
+ * that is part of a longer value is labeled by the longer one.
+ */
+function mergeRanges(ranges) {
+    const sorted = [...ranges].sort((a, b) => a.Start - b.Start || b.End - a.End);
+    const merged = [];
+    for (const range of sorted) {
+        const last = merged[merged.length - 1];
+        if (last && range.End <= last.End) {
+            continue;
+        }
+        if (last && range.Start < last.End) {
+            last.End = range.End;
+            last.Names.push(...range.Names);
+        }
+        else {
+            merged.push({ Start: range.Start, End: range.End, Names: [...range.Names] });
+        }
+    }
+    return merged;
+}
+/** Escapes the characters that have a meaning in a regular expression. */
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+//# sourceMappingURL=env-display.js.map

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

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

package/dist/lib/env-reference.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @fileoverview Parsing and checks for `@env:` references in metadata files.
+ * @module env-reference
+ */
+/** Matches `@env:VARIABLE`, with an optional `?optional` modifier. */
+export declare const ENV_REFERENCE_PATTERN: RegExp;
+/** A parsed `@env:` reference. */
+export interface EnvReference {
+    /** Name of the environment variable. */
+    VariableName: string;
+    /** True when the reference ends with `?optional`. */
+    Optional: boolean;
+}
+/**
+ * Parses an `@env:` reference.
+ * @returns The parsed reference, or null when the value is not a valid `@env:` reference
+ */
+export declare function ParseEnvReference(value: unknown): EnvReference | null;
+/** True when an environment value is `true` or `1`, ignoring case and surrounding spaces. */
+export declare function IsEnvFlagTrue(value: string | undefined): boolean;
+/** Thrown when an `@env:VAR?optional` reference names a variable that is not set. */
+export declare class OptionalEnvMissingError extends Error {
+    readonly VariableName: string;
+    constructor(variableName: string);
+}
+/** Thrown when a non-optional `@env:` reference names a variable that is not set. Holds names only. */
+export declare class EnvVariableNotSetError extends Error {
+    readonly VariableName: string;
+    /**
+     * The field that uses the reference, such as `fields.Description`, `primaryKey.ID` or
+     * `collections.Lines[0].fields.Name` for a composition child, when known.
+     */
+    readonly Field: string | undefined;
+    /** The entity of the record that holds the field, when it is not the record push reports. */
+    readonly EntityName: string | undefined;
+    constructor(variableName: string, field?: string, entityName?: string);
+    /** The same error for the given field (and entity, when given). */
+    ForField(field: string, entityName?: string): EnvVariableNotSetError;
+    /** The same error inside a composition path, such as `collections.Lines[0]`; an entity already named is kept. */
+    Within(compositionPath: string, entityName: string | undefined): EnvVariableNotSetError;
+}
+/** The warning push gives when it leaves out a field whose optional variable is not set. */
+export declare function OptionalEnvSkipMessage(entityName: string, fieldName: string, variableName: string): string;
+/** How a kept `@env:` reference compares with the database value. */
+export type EnvReferenceCheck = 'Match' | 'Drift' | 'Unset';
+/** An `@env:` reference that pull writes back in place of the database value. */
+export interface KeptEnvReference {
+    /** The reference exactly as the existing file has it. */
+    Reference: string;
+    VariableName: string;
+    Check: EnvReferenceCheck;
+}
+/**
+ * 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 declare function KeepEnvReference(existingValue: unknown, databaseValue: unknown, env?: NodeJS.ProcessEnv): KeptEnvReference | null;
+/** A JSON value. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** A JSON object or array. */
+export type JsonContainer = JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** True for a plain object or an array. */
+export declare function IsJsonContainer(value: unknown): value is JsonContainer;
+/** True when an object or array holds a valid `@env:` string at any depth. */
+export declare function HasNestedEnvReference(value: unknown): boolean;
+/** One `@env:` reference inside a JSON field that pull keeps. Never holds a value. */
+export interface KeptNestedEnvReference {
+    /** Path inside the field: `auth.apiKey`, `items[2].token`, `["x.y"]`. */
+    Path: string;
+    /** The reference exactly as the existing file has it. */
+    Reference: string;
+    VariableName: string;
+    Check: EnvReferenceCheck;
+}
+/** What pull writes for a JSON field that holds `@env:` references. */
+export interface NestedEnvKeepResult {
+    /** The database JSON with each kept reference put back, or the file value when `KeptFileValue` is true. */
+    Value: JsonValue;
+    Kept: KeptNestedEnvReference[];
+    /**
+     * True when the file value is kept as is: the database value is not a JSON object or array, or the
+     * merged database JSON still held a referenced variable's trimmed value of 6 or more characters.
+     */
+    KeptFileValue: boolean;
+    /**
+     * Names of the variables whose value the merged database JSON still held, sorted. Not empty only
+     * when `KeptFileValue` is true for this reason.
+     */
+    LeftValueVariables: string[];
+}
+/**
+ * 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 declare function KeepNestedEnvReferences(existingValue: unknown, databaseValue: unknown, env?: NodeJS.ProcessEnv): NestedEnvKeepResult | null;
+//# sourceMappingURL=env-reference.d.ts.map

package/dist/lib/env-reference.d.ts.map

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