@skmtc/core 0.0.984 → 0.16.1

package/script/typescript/List.js

@@ -1,509 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.EntryList = exports.KeyList = exports.List = void 0;
-/**
- * A powerful utility class for building formatted lists of stringable items.
- *
- * The `List` class is a core component of the SKMTC DSL system, providing type-safe
- * construction of formatted lists with customizable separators and bookends. It's
- * extensively used throughout the codebase for generating code constructs like
- * function parameters, object properties, array literals, and more.
- *
- * ## Type Safety
- *
- * The class uses TypeScript's generic system to provide compile-time guarantees
- * about the list structure, separator, and bookend styles. This enables rich
- * type inference and helps prevent formatting errors.
- *
- * ## Common Patterns
- *
- * - **Objects**: `List.toObject()` creates `{key: value, ...}` structures
- * - **Arrays**: `List.toArray()` creates `[item, item, ...]` structures
- * - **Parameters**: `List.toParams()` creates `(param, param, ...)` structures
- * - **Lines**: `List.toLines()` creates newline-separated content
- *
- * @template Values - Array of stringable values
- * @template Separator - String used to separate items
- * @template Bookends - Style of bookends ('[]', '{}', '()', 'none')
- *
- * @example Basic usage
- * ```typescript
- * import { List } from '@skmtc/core';
- *
- * // Create a comma-separated list
- * const items = new List(['apple', 'banana', 'cherry']);
- * console.log(items.toString()); // "apple, banana, cherry"
- *
- * // Create an array-style list
- * const array = new List(['a', 'b', 'c'], { bookends: '[]' });
- * console.log(array.toString()); // "[a, b, c]"
- *
- * // Create an object-style list
- * const obj = new List(['x: 1', 'y: 2'], { bookends: '{}' });
- * console.log(obj.toString()); // "{x: 1, y: 2}"
- * ```
- *
- * @example Using type aliases
- * ```typescript
- * // Type-safe array construction
- * const params: ListParams<string> = List.toParams(['id', 'name', 'email']);
- * console.log(params.toString()); // "(id, name, email)"
- *
- * // Object properties with filtering
- * const props = List.toObject(['title', undefined, 'author'], { skipEmpty: true });
- * console.log(props.toString()); // "{title, author}"
- *
- * // Line-separated content
- * const lines = List.toLines(['import React from "react"', 'import { useState } from "react"']);
- * console.log(lines.toString());
- * // import React from "react"
- * // import { useState } from "react"
- * ```
- *
- * @example Advanced usage with builders
- * ```typescript
- * // Function signature generation
- * const signature = List.toParams([
- *   'id: string',
- *   'options?: RequestOptions',
- *   'callback?: (result: T) => void'
- * ]);
- *
- * // Interface properties
- * const interfaceProps = List.toObject([
- *   'readonly id: string',
- *   'name: string',
- *   'createdAt: Date',
- *   'updatedAt?: Date'
- * ]);
- *
- * console.log(`interface User ${interfaceProps}`);
- * // interface User {readonly id: string, name: string, createdAt: Date, updatedAt?: Date}
- * ```
- */
-class List {
-    /**
-     * Creates a new List instance.
-     *
-     * @param values - Array of values (undefined values are automatically filtered out)
-     * @param options - Configuration options
-     * @param options.separator - String to use between items (default: ', ')
-     * @param options.bookends - Style of bookends to wrap the list (default: 'none')
-     * @param options.skipEmpty - Whether to return empty string for empty lists (default: false)
-     *
-     * @example
-     * ```typescript
-     * // Basic list with default comma separator
-     * const basic = new List(['a', 'b', 'c']);
-     *
-     * // Custom separator and bookends
-     * const custom = new List(['x', 'y', 'z'], {
-     *   separator: ' | ',
-     *   bookends: '[]',
-     *   skipEmpty: true
-     * });
-     * ```
-     */
-    constructor(values, { separator, bookends, skipEmpty } = {}) {
-        /** The array of values in this list */
-        Object.defineProperty(this, "values", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        /** The separator string used between items */
-        Object.defineProperty(this, "separator", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        /** The bookend style for wrapping the list */
-        Object.defineProperty(this, "bookends", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        /** Whether to skip rendering when the list is empty */
-        Object.defineProperty(this, "skipEmpty", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        this.values = values.filter(value => value !== undefined);
-        this.separator = separator ?? ', ';
-        this.bookends = bookends ?? 'none';
-        this.skipEmpty = skipEmpty ?? false;
-    }
-    /**
-     * Converts the list to its string representation.
-     *
-     * Joins all values with the configured separator and wraps with bookends.
-     * Returns empty string if skipEmpty is enabled and list is empty.
-     *
-     * @returns Formatted string representation of the list
-     */
-    toString() {
-        if (this.skipEmpty && this.values.length === 0) {
-            return '';
-        }
-        const joined = this.values.map(value => value.toString()).join(this.separator);
-        switch (this.bookends) {
-            case '[]':
-                return `[${joined}]`;
-            case '{}':
-                return `{${joined}}`;
-            case '()':
-                return `(${joined})`;
-            case 'none':
-                return joined;
-            default: {
-                const _exhaustive = this.bookends;
-                throw new Error(`Unhandled bookends type: ${_exhaustive}`);
-            }
-        }
-    }
-}
-exports.List = List;
-/**
- * Create an empty List that will render as an empty string ''
- * @returns List
- */
-Object.defineProperty(List, "toEmpty", {
-    enumerable: true,
-    configurable: true,
-    writable: true,
-    value: () => {
-        return new List([], { bookends: 'none' });
-    }
-});
-/**
- * Create a List with a single value that will render as `value`
- * @param value
- * @returns List
- */
-Object.defineProperty(List, "toSingle", {
-    enumerable: true,
-    configurable: true,
-    writable: true,
-    value: (value) => {
-        return new List([value], { bookends: 'none' });
-    }
-});
-/**
- * If condition is true, return a List with a single value that will render as `value`.
- * Otherwise, return an empty List that will render as an empty string ''.
- *
- * Useful for conditional rendering. For example, rendering a function arg object when
- * it has at least one property.
- * @param value
- * @param condition
- * @returns List
- */
-Object.defineProperty(List, "toConditional", {
-    enumerable: true,
-    configurable: true,
-    writable: true,
-    value: (value, condition) => {
-        const out = new List([condition ? value : undefined], { bookends: 'none' });
-        return out;
-    }
-});
-/**
- * Create a record with Stringable values. KeyValue pairs will be joined with `: ` as separator
- * and the resulting List will be wrapped with `{}`
- * @param record
- * @returns `record` with `Stringable` values
- */
-Object.defineProperty(List, "toRecord", {
-    enumerable: true,
-    configurable: true,
-    writable: true,
-    value: (record) => {
-        const entries = Object.entries(record).map(([key, value]) => {
-            return List.toKeyValue(key, value);
-        });
-        return List.toObject(entries);
-    }
-});
-/**
- * Create a record with `undefined` or empty array or List values filtered out.
- * @param record
- * @returns `record` with `undefined` values filtered out
- */
-Object.defineProperty(List, "toFilteredRecord", {
-    enumerable: true,
-    configurable: true,
-    writable: true,
-    value: (record) => {
-        const entries = Object.entries(record).map(([key, value]) => {
-            return List.toFilteredKeyValue(key, value);
-        });
-        return List.toObject(entries);
-    }
-});
-/**
- * Join `key` and `value` using `: ` as separator
- * @param key
- * @param value
- * @returns `key` and `value` joined with `: ` as separator
- */
-Object.defineProperty(List, "toKeyValue", {
-    enumerable: true,
-    configurable: true,
-    writable: true,
-    value: (key, value) => {
-        return new List([key, value], { separator: ': ' });
-    }
-});
-/**
- * Join `key` and `value` using `.` as separator
- * @param key
- * @param value
- * @returns `key` and `value` joined with `.` as separator
- */
-Object.defineProperty(List, "toObjectKey", {
-    enumerable: true,
-    configurable: true,
-    writable: true,
-    value: (key, value) => {
-        return new List([key, value], {
-            separator: '.'
-        });
-    }
-});
-/**
- * Join `values` using `, ` as separator and wrap in `{` and `}`
- * @param values
- * @returns `values` joined with `, ` as separator and wrapped in `{` and `}`
- */
-Object.defineProperty(List, "toObject", {
-    enumerable: true,
-    configurable: true,
-    writable: true,
-    value: (values, { skipEmpty } = {}) => {
-        return new List(values, { bookends: '{}', skipEmpty });
-    }
-});
-/**
- * Join `values` using `, ` as separator and wrap in `[` and `]`
- * @param values
- * @returns `values` joined with `, ` as separator and wrapped in `{` and `}`
- */
-Object.defineProperty(List, "toArray", {
-    enumerable: true,
-    configurable: true,
-    writable: true,
-    value: (values) => {
-        return new List(values, { bookends: '[]' });
-    }
-});
-/**
- * Join `values` using `, ` as separator and wrap in `(` and `)`
- * @param values
- * @returns `values` joined with `, ` as separator and wrapped in `(` and `)`
- */
-Object.defineProperty(List, "toParams", {
-    enumerable: true,
-    configurable: true,
-    writable: true,
-    value: (values) => {
-        return new List(values, { bookends: '()' });
-    }
-});
-/**
- * Join `values` using `\n` as separator without a wrapper
- * @param values
- * @returns `values` joined with `\n` as separator without a wrapper
- */
-Object.defineProperty(List, "toLines", {
-    enumerable: true,
-    configurable: true,
-    writable: true,
-    value: (values) => {
-        return new List(values, { separator: '\n' });
-    }
-});
-/**
- * Create a KeyList using the keys of @param record
- * @afdafg
- * @param record
- * @returns KeyList
- */
-Object.defineProperty(List, "fromKeys", {
-    enumerable: true,
-    configurable: true,
-    writable: true,
-    value: (record) => {
-        return new KeyList(Object.keys(record ?? {}));
-    }
-});
-/**
- * Create a EntryList using the entries of @param record
- * @afdafg
- * @param record
- * @returns EntryList
- */
-Object.defineProperty(List, "fromEntries", {
-    enumerable: true,
-    configurable: true,
-    writable: true,
-    value: (record) => {
-        return new EntryList(Object.entries(record ?? {}));
-    }
-});
-/**
- * Create a keyValue pair if `value` is not undefined and is not an empty array or List.
- * Return `undefined` otherwise.
- *
- * Useful for filtering out `undefined values from a record.
- * @param key
- * @param value
- * @returns `key` and `value` joined with `: ` as separator if `value` is not undefined and is not an empty array or List. `undefined` otherwise.
- */
-Object.defineProperty(List, "toFilteredKeyValue", {
-    enumerable: true,
-    configurable: true,
-    writable: true,
-    value: (key, value) => {
-        const out = List.hasValue(value) ? List.toKeyValue(key, value) : undefined;
-        return out;
-    }
-});
-/**
- * Check if `value` is not undefined and is not an empty array or List.
- * @param value
- * @returns `true` if `value` is not undefined and is not an empty array or List. `false` otherwise.
- */
-Object.defineProperty(List, "hasValue", {
-    enumerable: true,
-    configurable: true,
-    writable: true,
-    value: (value) => {
-        if (value === undefined) {
-            return false;
-        }
-        if (Array.isArray(value)) {
-            return value.length > 0;
-        }
-        if (value instanceof List) {
-            return List.hasValue(value.values);
-        }
-        return true;
-    }
-});
-/**
- * Utility class for working with arrays of string keys.
- *
- * Provides methods for transforming key arrays into objects and lists
- * with custom mapping functions.
- */
-class KeyList {
-    /**
-     * Creates a new KeyList instance.
-     *
-     * @param keys - Array of string keys to work with
-     */
-    constructor(keys) {
-        /** Array of string keys */
-        Object.defineProperty(this, "keys", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        this.keys = keys;
-    }
-    /**
-     * Transforms keys into an object using a mapping function.
-     *
-     * @param mapFn - Function to transform each key into a value
-     * @param options - Options for handling empty values
-     * @returns Object with keys mapped to transformed values
-     */
-    toObject(mapFn, { skipEmpty } = {}) {
-        return List.toObject(this.keys.map((key, index) => mapFn(key, index)), { skipEmpty });
-    }
-    /**
-     * Creates a plain object with keys as both keys and values.
-     *
-     * @returns Object where each key maps to itself
-     */
-    toObjectPlain() {
-        return List.toObject(this.keys);
-    }
-    /**
-     * Transforms keys into a List using a mapping function.
-     *
-     * @param mapFn - Function to transform each key into a value
-     * @returns List containing the transformed values
-     */
-    toLines(mapFn) {
-        return List.toLines(this.keys.map((key, index) => mapFn(key, index)));
-    }
-    /**
-     * Creates a List with keys as the values.
-     *
-     * @returns List containing the original keys
-     */
-    toLinesPlain() {
-        return List.toLines(this.keys);
-    }
-}
-exports.KeyList = KeyList;
-/**
- * Utility class for working with arrays of key-value pair entries.
- *
- * Provides methods for transforming entry arrays into objects and lists
- * with custom mapping functions.
- *
- * @template T - Type of the entry values
- */
-class EntryList {
-    /**
-     * Creates a new EntryList instance.
-     *
-     * @param entries - Array of key-value pair entries to work with
-     */
-    constructor(entries) {
-        /** Array of key-value pair entries */
-        Object.defineProperty(this, "entries", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        this.entries = entries;
-    }
-    /**
-     * Transforms entries into an object using a mapping function.
-     *
-     * @param mapFn - Function to transform each entry into a value
-     * @returns Object with transformed values
-     */
-    toObject(mapFn) {
-        return List.toObject(this.entries.map((entry, index) => mapFn(entry, index)));
-    }
-    /**
-     * Transforms entries into a List using a mapping function.
-     *
-     * @param mapFn - Function to transform each entry into a value
-     * @returns List containing the transformed values
-     */
-    toLines(mapFn) {
-        return List.toLines(this.entries.map((key, index) => mapFn(key, index)));
-    }
-    /**
-     * Transforms entries into an array using a mapping function.
-     *
-     * @param mapFn - Function to transform each entry into a value
-     * @returns Array containing the transformed values
-     */
-    toArray(mapFn) {
-        return List.toArray(this.entries.map((entry, index) => mapFn(entry, index)));
-    }
-}
-exports.EntryList = EntryList;