yini-parser 1.0.2-beta → 1.2.0-beta

package/dist/types/index.d.ts

@@ -0,0 +1,198 @@
+/**
+ *
+ * Public (user-facing) types (shapes) here only.
+ *
+ * @note Internal-only types (shapes) should go into core/internalTypes.ts.
+ * @note These types and interface (shapes) should NOT include the 'T' and,
+ *       'I' prefixes, due to these are public user-facing.
+ */
+import { TBailSensitivityLevel } from '../core/internalTypes';
+/**
+ * JavaScript object produced by parsing a YINI document.
+ */
+export type ParsedObject = any;
+/**
+ * Result returned from `parse(..)` and `parseFile(..)`,
+ * containing both the parsed object and associated metadata.
+ */
+export interface YiniParseResult {
+    result: ParsedObject;
+    meta: ResultMetadata;
+}
+export type FailLevelKey = 'ignore-errors' | 'errors' | 'warnings-and-errors';
+export type PreferredFailLevel = 'auto' | FailLevelKey;
+export type OnDuplicateKey = 'warn-and-keep-first' | 'warn-and-overwrite' | 'keep-first' | 'overwrite' | 'error';
+/** Version tag for the public metadata schema. */
+export type MetaSchemaVersion = '1.1.0';
+/** Source of the order guarantee. */
+export type OrderGuarantee = 'spec' | 'language' | 'implementation-defined' | 'none';
+/**
+ * User-facing options, these are external and should be more user friendly,
+ * and shorter, parameter names than the (more descriptive) internal
+ * engine option names.
+ *
+ * @note These parameters are emphasizes a bit more than the other options,
+ *       therefor these are kept a bit shorter for usability-purposes.
+ * @note These are the same as in the "simple positional API" function in
+ *       the YINI class.
+ */
+export interface PrimaryUserParams {
+    /** Enable stricter syntax and well-formedness checks. */
+    strictMode?: boolean;
+    /**
+     * Minimum severity that should cause parse to fail.
+     * 'auto' | 'ignore-errors' | 'errors' | 'warnings-and-errors'
+     */
+    failLevel?: PreferredFailLevel;
+    /** Attach metadata to the parse result (timings, diagnostics, etc.). */
+    includeMetadata?: boolean;
+}
+/**
+ * @param failLevel - Minimum severity that should cause the parse to fail.
+ *   Accepts:
+ *     `'ignore-errors'` - Don't bail/fail on error, persist and try to recover.
+ *     `'errors'` - Stop parsing on the first error.
+ *     `'warnings-and-errors'` - Stop parsing on the first warning or error.
+ *   (Type: TPreferredFailLevel; exact behavior is implementation-defined.)
+ * @param includeDiagnostics - Include diagnostics in the returned metadata.
+ *   Requires: `includeMetadata = true`. Ignored otherwise.
+ * @param includeMetadata - Attach a metadata object to the parse result
+ *   (e.g., timings, diagnostics).
+ * @param includeTiming - Include timing information for parser phases in metadata.
+ *   Requires: `includeMetadata = true`. Ignored otherwise.
+ * @param onDuplicateKey - Strategy/handler when encountering a duplicate key.
+ *   Allowed values: `'warn-and-keep-first'` | `'warn-and-overwrite'` | `'keep-first'` (silent, first wins) | `'overwrite'` (silent, last wins) | `'error'`.
+ * @param preserveUndefinedInMeta - Keep properties with value `undefined` inside
+ *   the returned metadata. Requires: `includeMetadata = true`. Ignored otherwise.
+ * @param requireDocTerminator - Controls whether a document terminator is required.
+ *   Allowed values: `'optional'` | `'warn-if-missing'` | `'required'`.
+ * @param strictMode - Enable stricter syntax and well-formedness checks according
+ *   to the spec (exact rules are implementation-defined).
+ * @param suppressWarnings - Suppress warnings sent to the console/log.
+ *   Does not affect warnings included in returned metadata.
+ * @param treatEmptyValueAsNull - How to treat an explicitly empty value on the
+ *   right-hand side of '='. Allowed values: `'allow'` | `'allow-with-warning'` | `'disallow'`.
+ */
+export interface AllUserOptions extends PrimaryUserParams {
+    includeDiagnostics?: boolean;
+    includeTiming?: boolean;
+    preserveUndefinedInMeta?: boolean;
+    suppressWarnings?: boolean;
+    requireDocTerminator?: 'optional' | 'warn-if-missing' | 'required';
+    treatEmptyValueAsNull?: 'allow' | 'allow-with-warning' | 'disallow';
+    onDuplicateKey?: OnDuplicateKey;
+}
+export interface IssuePayload {
+    /** 1-based; use undefined when not applicable. */
+    line: number | undefined;
+    /** 1-based; use undefined when not applicable. */
+    column: number | undefined;
+    /** Lowercase key for easy tooling. */
+    typeKey: string;
+    message: string;
+    advice: string | undefined;
+    hint: string | undefined;
+}
+/**
+ * @note NOTE: USE NO TYPES here (or neither in nested structures), they
+ *       should only be strings (and content MUST be transformed from the
+ *       types to lower snake case)
+ *
+ *       *** DUE TO make easier for tooling ***
+ *
+ * @note UPDATE 'metaSchemaVersion' on any edits to the meta structure.
+ */
+export interface ResultMetadata {
+    parserVersion: string;
+    mode: 'lenient' | 'strict';
+    totalErrors: number;
+    totalWarnings: number;
+    totalMessages: number;
+    runStartedAt: string;
+    runFinishedAt: string;
+    durationMs: number;
+    preservesOrder: boolean;
+    orderGuarantee: OrderGuarantee;
+    orderNotes?: string;
+    source: {
+        sourceType: string;
+        fileName: undefined | string;
+        hasDocumentTerminator: boolean;
+        hasYiniMarker: boolean;
+        byteSize: null | number;
+        lineCount: null | number;
+        sha256: null | string;
+    };
+    structure: {
+        maxDepth: null | number;
+        sectionCount: null | number;
+        memberCount: null | number;
+        keysParsedCount: null | number;
+        sectionNamePaths: string[] | null;
+    };
+    metaSchemaVersion: MetaSchemaVersion;
+    diagnostics?: {
+        failLevel: {
+            preferredLevel: null | PreferredFailLevel;
+            usedLevelType: TBailSensitivityLevel;
+            usedLevelKey: FailLevelKey;
+            levelDescription: string | null;
+        };
+        errors: {
+            errorCount: number;
+            payload: IssuePayload[];
+        };
+        warnings: {
+            warningCount: number;
+            payload: IssuePayload[];
+        };
+        notices: {
+            noticeCount: number;
+            payload: IssuePayload[];
+        };
+        infos: {
+            infoCount: number;
+            payload: IssuePayload[];
+        };
+        environment: {
+            NODE_ENV: undefined | string;
+            APP_ENV: undefined | string;
+            lib: {
+                nodeEnv: undefined | string;
+                appEnv: undefined | string;
+                flags: {
+                    isDev: boolean;
+                    isDebug: boolean;
+                };
+            };
+        };
+        effectiveOptions: AllUserOptions;
+        options: AllUserOptions;
+    };
+    timing?: {
+        total: null | {
+            timeMs: number;
+            name: string;
+        };
+        phase0: undefined | {
+            timeMs: number;
+            name: string;
+        };
+        phase1: null | {
+            timeMs: number;
+            name: string;
+        };
+        phase2: null | {
+            timeMs: number;
+            name: string;
+        };
+        phase3: null | {
+            timeMs: number;
+            name: string;
+        };
+        phase4: null | {
+            timeMs: number;
+            name: string;
+        };
+    };
+}

package/dist/types/index.js

@@ -0,0 +1,4 @@
+"use strict";
+// File: src/types/index.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":";AAAA,2BAA2B"}

package/dist/utils/number.d.ts

@@ -0,0 +1,3 @@
+export declare const isNaNValue: (n: number) => boolean;
+export declare const isInfinityValue: (n: number) => boolean;
+export declare const isValidJSNumber: (str: string) => boolean;

package/dist/utils/number.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidJSNumber = exports.isInfinityValue = exports.isNaNValue = void 0;
+const isNaNValue = (n) => {
+    return Number.isNaN(n);
+};
+exports.isNaNValue = isNaNValue;
+const isInfinityValue = (n) => {
+    return n === Infinity || n === -Infinity;
+};
+exports.isInfinityValue = isInfinityValue;
+const isValidJSNumber = (str) => {
+    if (str.trim() === '')
+        return false; // Reject empty or whitespace-only.
+    const n = Number(str);
+    return !Number.isNaN(n); // True only if parse succeeded.
+};
+exports.isValidJSNumber = isValidJSNumber;
+//# sourceMappingURL=number.js.map

package/dist/utils/number.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"number.js","sourceRoot":"","sources":["../../src/utils/number.ts"],"names":[],"mappings":";;;AAAO,MAAM,UAAU,GAAG,CAAC,CAAS,EAAW,EAAE;IAC7C,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;AAC1B,CAAC,CAAA;AAFY,QAAA,UAAU,cAEtB;AAEM,MAAM,eAAe,GAAG,CAAC,CAAS,EAAW,EAAE;IAClD,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAA;AAC5C,CAAC,CAAA;AAFY,QAAA,eAAe,mBAE3B;AAEM,MAAM,eAAe,GAAG,CAAC,GAAW,EAAW,EAAE;IACpD,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,KAAK,CAAA,CAAC,mCAAmC;IACvE,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAA;IACrB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA,CAAC,gCAAgC;AAC5D,CAAC,CAAA;AAJY,QAAA,eAAe,mBAI3B"}

package/dist/utils/object.d.ts

@@ -0,0 +1,67 @@
+interface SortOptions {
+    /** Sort nested objects too (default: false) */
+    deep?: boolean;
+    /** Custom key comparator (default: a.localeCompare(b)) */
+    comparator?: (a: string, b: string) => number;
+}
+/**
+ * Returns a new object with keys sorted alphabetically.
+ * Arrays and non-plain objects are preserved as-is (unless deep + they contain plain objects).
+ */
+export declare const sortObjectKeys: <T>(obj: T, options?: SortOptions) => T;
+/**
+ * Removes top-level properties with value `undefined`.
+ * Does not recurse into nested objects or arrays.
+ *
+ * @param obj Any JS object
+ * @returns A shallow copy with undefined properties removed,
+ *          except in nested objects or arrays.
+ *
+ * @example
+ * Input:
+ * const input = {
+ *     a: 1,
+ *     b: undefined,
+ *     c: { d: undefined, e: 2 },
+ *     f: [1, undefined, 2]
+ * };
+ *
+ * Output:
+ *   {
+ *     a: 1,
+ *     c: { d: undefined, e: 2 },
+ *     f: [1, undefined, 2]
+ *   }
+ */
+export declare const removeUndefinedShallow: <T extends object>(obj: T) => Partial<T>;
+/**
+ * Recursively removes properties with value `undefined` from objects
+ * and arrays.
+ *
+ * @param obj Any JS value (object, array, primitive)
+ * @returns A deep-cloned copy with all `undefined` removed, including in
+ *          nested objects and arrays.
+ *
+ * @example
+ * Input:
+ *   const input = {
+ *       a: 1,
+ *       b: undefined,
+ *       c: {
+ *           d: undefined,
+ *           e: 2,
+ *           f: [1, undefined, { g: undefined, h: 42 }]
+ *       }
+ *   };
+ *
+ * Output:
+ *   {
+ *     a: 1,
+ *     c: {
+ *         e: 2,
+ *         f: [1, { h: 42 }]
+ *     }
+ *   }
+ */
+export declare const removeUndefinedDeep: <T>(obj: T) => T;
+export {};

package/dist/utils/object.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.removeUndefinedDeep = exports.removeUndefinedShallow = exports.sortObjectKeys = void 0;
+const isPlainObject = (value) => {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.prototype.toString.call(value) === '[object Object]');
+};
+/**
+ * Returns a new object with keys sorted alphabetically.
+ * Arrays and non-plain objects are preserved as-is (unless deep + they contain plain objects).
+ */
+const sortObjectKeys = (obj, options = {}) => {
+    const { deep = false, comparator } = options;
+    if (!isPlainObject(obj)) {
+        // If it's not a plain object (array, Date, null, primitive), return as-is.
+        return obj;
+    }
+    const keys = Object.keys(obj).sort(comparator ?? ((a, b) => a.localeCompare(b)));
+    const sortedEntries = keys.map((k) => {
+        const value = obj[k];
+        if (deep) {
+            if (isPlainObject(value)) {
+                return [k, (0, exports.sortObjectKeys)(value, options)];
+            }
+            if (Array.isArray(value)) {
+                // Deep-sort any plain objects inside arrays, leave others as-is.
+                return [
+                    k,
+                    value.map((item) => isPlainObject(item)
+                        ? (0, exports.sortObjectKeys)(item, options)
+                        : item),
+                ];
+            }
+        }
+        return [k, value];
+    });
+    // Preserve the original type T structurally.
+    return Object.fromEntries(sortedEntries);
+};
+exports.sortObjectKeys = sortObjectKeys;
+/**
+ * Removes top-level properties with value `undefined`.
+ * Does not recurse into nested objects or arrays.
+ *
+ * @param obj Any JS object
+ * @returns A shallow copy with undefined properties removed,
+ *          except in nested objects or arrays.
+ *
+ * @example
+ * Input:
+ * const input = {
+ *     a: 1,
+ *     b: undefined,
+ *     c: { d: undefined, e: 2 },
+ *     f: [1, undefined, 2]
+ * };
+ *
+ * Output:
+ *   {
+ *     a: 1,
+ *     c: { d: undefined, e: 2 },
+ *     f: [1, undefined, 2]
+ *   }
+ */
+const removeUndefinedShallow = (obj) => {
+    const cleaned = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (value !== undefined) {
+            cleaned[key] = value;
+        }
+    }
+    return cleaned;
+};
+exports.removeUndefinedShallow = removeUndefinedShallow;
+/**
+ * Recursively removes properties with value `undefined` from objects
+ * and arrays.
+ *
+ * @param obj Any JS value (object, array, primitive)
+ * @returns A deep-cloned copy with all `undefined` removed, including in
+ *          nested objects and arrays.
+ *
+ * @example
+ * Input:
+ *   const input = {
+ *       a: 1,
+ *       b: undefined,
+ *       c: {
+ *           d: undefined,
+ *           e: 2,
+ *           f: [1, undefined, { g: undefined, h: 42 }]
+ *       }
+ *   };
+ *
+ * Output:
+ *   {
+ *     a: 1,
+ *     c: {
+ *         e: 2,
+ *         f: [1, { h: 42 }]
+ *     }
+ *   }
+ */
+const removeUndefinedDeep = (obj) => {
+    if (obj === null || typeof obj !== 'object') {
+        return obj; // primitive value
+    }
+    if (Array.isArray(obj)) {
+        // Clean each element, and filter out undefined entries
+        return obj
+            .map((item) => (0, exports.removeUndefinedDeep)(item))
+            .filter((item) => item !== undefined);
+    }
+    const cleaned = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (value !== undefined) {
+            cleaned[key] = (0, exports.removeUndefinedDeep)(value);
+        }
+    }
+    return cleaned;
+};
+exports.removeUndefinedDeep = removeUndefinedDeep;
+//# sourceMappingURL=object.js.map

package/dist/utils/object.js.map

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

package/dist/utils/pathAndFileName.js

@@ -13,3 +13,4 @@ const getFileNameExtension = (fullPath) => {
     return path_1.default.extname(fullPath);
 };
 exports.getFileNameExtension = getFileNameExtension;
+//# sourceMappingURL=pathAndFileName.js.map

package/dist/utils/pathAndFileName.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pathAndFileName.js","sourceRoot":"","sources":["../../src/utils/pathAndFileName.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;AAEH,gDAAuB;AAEhB,MAAM,oBAAoB,GAAG,CAAC,QAAgB,EAAU,EAAE;IAC7D,OAAO,cAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;AACjC,CAAC,CAAA;AAFY,QAAA,oBAAoB,wBAEhC"}

package/dist/utils/print.d.ts

@@ -4,10 +4,10 @@ export declare const toPrettyJSON: (obj: any) => string;
 /** Pretty-prints a JavaScript object as formatted JSON to the console.
  * Strict JSON, all keys are enclosed in ", etc.
  */
-export declare const printJSON: (obj: any) => void;
+export declare const printJSON: (obj: any, isForce?: boolean) => void;
 /**
  * Print a full JavaScript object in a human-readable way (not as JSON).
  * Not strict JSON, and shows functions, symbols, getters/setters, and class names.
  * @param isColors If true, the output is styled with ANSI color codes.
  */
-export declare const printObject: (obj: any, isColors?: boolean) => void;
+export declare const printObject: (obj: any, isForce?: boolean, isColors?: boolean) => void;

package/dist/utils/print.js

@@ -26,9 +26,11 @@ exports.toPrettyJSON = toPrettyJSON;
 /** Pretty-prints a JavaScript object as formatted JSON to the console.
  * Strict JSON, all keys are enclosed in ", etc.
  */
-const printJSON = (obj) => {
-    if ((0, env_1.isProdEnv)() || ((0, env_1.isTestEnv)() && !(0, env_1.isDebug)()))
-        return;
+const printJSON = (obj, isForce = false) => {
+    if (!isForce) {
+        if ((0, env_1.isProdEnv)() || ((0, env_1.isTestEnv)() && !(0, env_1.isDebug)()))
+            return;
+    }
     const str = (0, exports.toPrettyJSON)(obj);
     console.log(str);
 };
@@ -38,9 +40,12 @@ exports.printJSON = printJSON;
  * Not strict JSON, and shows functions, symbols, getters/setters, and class names.
  * @param isColors If true, the output is styled with ANSI color codes.
  */
-const printObject = (obj, isColors = true) => {
-    if ((0, env_1.isProdEnv)() || ((0, env_1.isTestEnv)() && !(0, env_1.isDebug)()))
-        return;
+const printObject = (obj, isForce = false, isColors = true) => {
+    if (!isForce) {
+        if ((0, env_1.isProdEnv)() || ((0, env_1.isTestEnv)() && !(0, env_1.isDebug)()))
+            return;
+    }
     console.log(util_1.default.inspect(obj, { depth: null, colors: isColors }));
 };
 exports.printObject = printObject;
+//# sourceMappingURL=print.js.map

package/dist/utils/print.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"print.js","sourceRoot":"","sources":["../../src/utils/print.ts"],"names":[],"mappings":";;;;;;AAAA;;;GAGG;AACH,gDAAuB;AACvB,uCAAoE;AAE7D,MAAM,UAAU,GAAG,CAAC,MAAW,EAAE,EAAE,EAAE;IACxC,IAAA,aAAO,GAAE,IAAI,OAAO,CAAC,KAAK,CAAC,SAAS,GAAG,GAAG,CAAC,CAAA;AAC/C,CAAC,CAAA;AAFY,QAAA,UAAU,cAEtB;AAEM,MAAM,QAAQ,GAAG,CAAC,MAAW,EAAE,EAAE,EAAE;IACtC,IAAA,WAAK,GAAE,IAAI,CAAC,IAAA,eAAS,GAAE,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,GAAG,GAAG,CAAC,CAAA;AACzD,CAAC,CAAA;AAFY,QAAA,QAAQ,YAEpB;AAEM,MAAM,YAAY,GAAG,CAAC,GAAQ,EAAU,EAAE;IAC7C,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;IACxC,OAAO,GAAG,CAAA;AACd,CAAC,CAAA;AAHY,QAAA,YAAY,gBAGxB;AAED;;GAEG;AACI,MAAM,SAAS,GAAG,CAAC,GAAQ,EAAE,OAAO,GAAG,KAAK,EAAE,EAAE;IACnD,IAAI,CAAC,OAAO,EAAE,CAAC;QACX,IAAI,IAAA,eAAS,GAAE,IAAI,CAAC,IAAA,eAAS,GAAE,IAAI,CAAC,IAAA,aAAO,GAAE,CAAC;YAAE,OAAM;IAC1D,CAAC;IAED,MAAM,GAAG,GAAG,IAAA,oBAAY,EAAC,GAAG,CAAC,CAAA;IAC7B,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;AACpB,CAAC,CAAA;AAPY,QAAA,SAAS,aAOrB;AAED;;;;GAIG;AACI,MAAM,WAAW,GAAG,CAAC,GAAQ,EAAE,OAAO,GAAG,KAAK,EAAE,QAAQ,GAAG,IAAI,EAAE,EAAE;IACtE,IAAI,CAAC,OAAO,EAAE,CAAC;QACX,IAAI,IAAA,eAAS,GAAE,IAAI,CAAC,IAAA,eAAS,GAAE,IAAI,CAAC,IAAA,aAAO,GAAE,CAAC;YAAE,OAAM;IAC1D,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,cAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAA;AACrE,CAAC,CAAA;AANY,QAAA,WAAW,eAMvB"}

package/dist/utils/string.d.ts

@@ -2,12 +2,27 @@
  * This file contains general string helper functions (utils).
  * @note More specific YINI helper functions should go into yiniHelpers.ts-file.
  */
+/**
+ * Capitalizes the first character of a string.
+ *
+ * @param str The input string.
+ * @returns A new string with the first character uppercased.
+ */
+export declare const capitalizeFirst: (str: string) => string;
+export declare const computeSha256: (content: string) => string;
 /**
  * Splits a string into an array of lines, handling both LF and CRLF newlines.
  * @param content The input string.
  * @returns Array of lines (strings).
  */
-export declare function splitLines(content: string): string[];
+export declare const splitLines: (content: string) => string[];
+/**
+ * Trims trailing non-letter characters (A–Z, a–z) from the end of a string.
+ *
+ * @param str Input string
+ * @returns String with trailing non-letters removed
+ */
+export declare const trimTrailingNonLetters: (str: string) => string;
 /**
  * If a string starts and ends with a backtick `, if so trims the
  * first and last character (the backticks).
@@ -40,3 +55,13 @@ export declare const isDigit: (character: string) => boolean;
  * @deprecated This seems not useful anymore, use stripCommentsAndAfter(..) instead.
  */
 export declare const stripNLAndAfter: (line: string) => string;
+/**
+ * Transforms strings such as 'Id-Name' to 'id_name'.
+ * Replaces all '-' to '_', and returns rusult in lower case.
+ */
+export declare const toLowerSnakeCase: (txt: string) => string;
+/**
+ * Transforms strings such as 'Id-Name' to 'id-name'.
+ * Replaces all '_' to '-', and returns rusult in lower case.
+ */
+export declare const toLowerKebabCase: (txt: string) => string;

package/dist/utils/string.js

@@ -4,18 +4,45 @@
  * @note More specific YINI helper functions should go into yiniHelpers.ts-file.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stripNLAndAfter = exports.isDigit = exports.isAlpha = exports.isEnclosedInBackticks = exports.trimBackticks = void 0;
-exports.splitLines = splitLines;
+exports.toLowerKebabCase = exports.toLowerSnakeCase = exports.stripNLAndAfter = exports.isDigit = exports.isAlpha = exports.isEnclosedInBackticks = exports.trimBackticks = exports.trimTrailingNonLetters = exports.splitLines = exports.computeSha256 = exports.capitalizeFirst = void 0;
+const crypto_1 = require("crypto");
 const print_1 = require("./print");
+/**
+ * Capitalizes the first character of a string.
+ *
+ * @param str The input string.
+ * @returns A new string with the first character uppercased.
+ */
+const capitalizeFirst = (str) => {
+    if (!str)
+        return str;
+    return str.charAt(0).toUpperCase() + str.slice(1);
+};
+exports.capitalizeFirst = capitalizeFirst;
+const computeSha256 = (content) => {
+    return (0, crypto_1.createHash)('sha256').update(content, 'utf8').digest('hex');
+};
+exports.computeSha256 = computeSha256;
 /**
  * Splits a string into an array of lines, handling both LF and CRLF newlines.
  * @param content The input string.
  * @returns Array of lines (strings).
  */
-function splitLines(content) {
+const splitLines = (content) => {
     // Chould handle \n (LF), \r\n (CRLF), and even just \r (old Mac style).
     return content.split(/\r\n|\r|\n/);
-}
+};
+exports.splitLines = splitLines;
+/**
+ * Trims trailing non-letter characters (A–Z, a–z) from the end of a string.
+ *
+ * @param str Input string
+ * @returns String with trailing non-letters removed
+ */
+const trimTrailingNonLetters = (str) => {
+    return str.replace(/[^a-zA-Z]+$/g, '');
+};
+exports.trimTrailingNonLetters = trimTrailingNonLetters;
 /**
  * If a string starts and ends with a backtick `, if so trims the
  * first and last character (the backticks).
@@ -95,3 +122,20 @@ const stripNLAndAfter = (line) => {
     return resultLine;
 };
 exports.stripNLAndAfter = stripNLAndAfter;
+/**
+ * Transforms strings such as 'Id-Name' to 'id_name'.
+ * Replaces all '-' to '_', and returns rusult in lower case.
+ */
+const toLowerSnakeCase = (txt) => {
+    return txt.trim().toLowerCase().replace(/[-]/g, '_');
+};
+exports.toLowerSnakeCase = toLowerSnakeCase;
+/**
+ * Transforms strings such as 'Id-Name' to 'id-name'.
+ * Replaces all '_' to '-', and returns rusult in lower case.
+ */
+const toLowerKebabCase = (txt) => {
+    return txt.trim().toLowerCase().replace(/[_]/g, '-');
+};
+exports.toLowerKebabCase = toLowerKebabCase;
+//# sourceMappingURL=string.js.map

package/dist/utils/string.js.map

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

package/dist/utils/system.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Error instance helper.
+ * @example
+ *   ...
+ *   } catch (err: unknown) {
+ *       if (err instanceof Error) {
+ *           console.error("Message:", err.message)
+ *           console.error("Stack:", err.stack)
+ *       } else {
+ *           console.error("Unknown error:", err)
+ *           console.error("Thrown value:", JSON.stringify(err))
+ *       }
+ *   }
+ */
+export declare const isError: (e: unknown) => e is Error;

package/dist/utils/system.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isError = void 0;
+/**
+ * Error instance helper.
+ * @example
+ *   ...
+ *   } catch (err: unknown) {
+ *       if (err instanceof Error) {
+ *           console.error("Message:", err.message)
+ *           console.error("Stack:", err.stack)
+ *       } else {
+ *           console.error("Unknown error:", err)
+ *           console.error("Thrown value:", JSON.stringify(err))
+ *       }
+ *   }
+ */
+const isError = (e) => {
+    return e instanceof Error;
+};
+exports.isError = isError;
+//# sourceMappingURL=system.js.map

package/dist/utils/system.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system.js","sourceRoot":"","sources":["../../src/utils/system.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;GAaG;AACI,MAAM,OAAO,GAAG,CAAC,CAAU,EAAc,EAAE;IAC9C,OAAO,CAAC,YAAY,KAAK,CAAA;AAC7B,CAAC,CAAA;AAFY,QAAA,OAAO,WAEnB"}