@skmtc/core 0.0.792 → 0.0.794

package/esm/typescript/identifiers.d.ts

@@ -1,3 +1,162 @@
+/**
+ * Safely formats a key for use in object literals, adding quotes if needed.
+ *
+ * This function determines whether a property key needs to be quoted in JavaScript/TypeScript
+ * object literals based on identifier naming rules. Valid identifiers are left unquoted,
+ * while invalid identifiers (containing spaces, special characters, starting with numbers, etc.)
+ * are wrapped in single quotes.
+ *
+ * @param key - The property key to format
+ * @returns The key as-is if it's a valid identifier, otherwise wrapped in quotes
+ *
+ * @example Valid identifiers (no quotes needed)
+ * ```typescript
+ * import { handleKey } from '@skmtc/core';
+ *
+ * console.log(handleKey('name'));      // 'name'
+ * console.log(handleKey('userName'));  // 'userName'
+ * console.log(handleKey('_private'));  // '_private'
+ * console.log(handleKey('$special'));  // '$special'
+ * ```
+ *
+ * @example Invalid identifiers (quotes added)
+ * ```typescript
+ * console.log(handleKey('first-name'));  // "'first-name'"
+ * console.log(handleKey('2nd-place'));   // "'2nd-place'"
+ * console.log(handleKey('user name'));   // "'user name'"
+ * console.log(handleKey('api-key'));     // "'api-key'"
+ * console.log(handleKey('data.nested')); // "'data.nested'"
+ * ```
+ *
+ * @example Usage in object generation
+ * ```typescript
+ * class ObjectGenerator {
+ *   generateObjectLiteral(properties: Record<string, string>) {
+ *     const props = Object.entries(properties)
+ *       .map(([key, value]) => `${handleKey(key)}: ${value}`)
+ *       .join(', ');
+ *
+ *     return `{ ${props} }`;
+ *   }
+ * }
+ *
+ * const generator = new ObjectGenerator();
+ * const result = generator.generateObjectLiteral({
+ *   'name': 'string',
+ *   'first-name': 'string',
+ *   'age': 'number'
+ * });
+ *
+ * console.log(result);
+ * // { name: string, 'first-name': string, age: number }
+ * ```
+ *
+ * @example TypeScript interface generation
+ * ```typescript
+ * function generateInterface(name: string, properties: Record<string, string>) {
+ *   const props = Object.entries(properties)
+ *     .map(([key, type]) => `  ${handleKey(key)}: ${type};`)
+ *     .join('\n');
+ *
+ *   return `interface ${name} {\n${props}\n}`;
+ * }
+ *
+ * const userInterface = generateInterface('User', {
+ *   'id': 'string',
+ *   'first-name': 'string',
+ *   'last_name': 'string',
+ *   '2fa-enabled': 'boolean'
+ * });
+ *
+ * console.log(userInterface);
+ * // interface User {
+ * //   id: string;
+ * //   'first-name': string;
+ * //   last_name: string;
+ * //   '2fa-enabled': boolean;
+ * // }
+ * ```
+ */
 export declare const handleKey: (key: string) => string;
+/**
+ * Safely formats property access, using dot notation or bracket notation as appropriate.
+ *
+ * This function generates the appropriate property access syntax for JavaScript/TypeScript
+ * code. Valid identifiers use dot notation (`parent.property`), while invalid identifiers
+ * use bracket notation (`parent['property']`).
+ *
+ * @param name - The property name to access
+ * @param parent - The parent object expression
+ * @returns Properly formatted property access expression
+ *
+ * @example Valid identifiers (dot notation)
+ * ```typescript
+ * import { handlePropertyName } from '@skmtc/core';
+ *
+ * console.log(handlePropertyName('name', 'user'));      // 'user.name'
+ * console.log(handlePropertyName('firstName', 'user')); // 'user.firstName'
+ * console.log(handlePropertyName('_id', 'document'));   // 'document._id'
+ * console.log(handlePropertyName('$meta', 'data'));     // 'data.$meta'
+ * ```
+ *
+ * @example Invalid identifiers (bracket notation)
+ * ```typescript
+ * console.log(handlePropertyName('first-name', 'user'));  // "user['first-name']"
+ * console.log(handlePropertyName('2nd-place', 'result')); // "result['2nd-place']"
+ * console.log(handlePropertyName('user name', 'form'));   // "form['user name']"
+ * console.log(handlePropertyName('api-key', 'config'));   // "config['api-key']"
+ * ```
+ *
+ * @example Usage in accessor generation
+ * ```typescript
+ * class PropertyAccessor {
+ *   generateGetter(objectName: string, propertyPath: string[]) {
+ *     return propertyPath.reduce((acc, prop) =>
+ *       handlePropertyName(prop, acc), objectName
+ *     );
+ *   }
+ * }
+ *
+ * const accessor = new PropertyAccessor();
+ * const path1 = accessor.generateGetter('data', ['user', 'profile', 'firstName']);
+ * const path2 = accessor.generateGetter('config', ['api-settings', 'retry-count']);
+ *
+ * console.log(path1); // 'data.user.profile.firstName'
+ * console.log(path2); // "config['api-settings']['retry-count']"
+ * ```
+ *
+ * @example Complex object navigation
+ * ```typescript
+ * function generateObjectAccess(base: string, properties: string[]) {
+ *   let result = base;
+ *
+ *   for (const prop of properties) {
+ *     result = handlePropertyName(prop, result);
+ *   }
+ *
+ *   return result;
+ * }
+ *
+ * const access1 = generateObjectAccess('response', ['data', 'user-info', 'name']);
+ * const access2 = generateObjectAccess('settings', ['ui', 'theme', 'darkMode']);
+ *
+ * console.log(access1); // "response.data['user-info'].name"
+ * console.log(access2); // "settings.ui.theme.darkMode"
+ * ```
+ *
+ * @example Function generation
+ * ```typescript
+ * function generatePropertyGetter(objName: string, propName: string) {
+ *   const access = handlePropertyName(propName, objName);
+ *   return `function get${propName.replace(/[^a-zA-Z0-9]/g, '')}() { return ${access}; }`;
+ * }
+ *
+ * const getter1 = generatePropertyGetter('user', 'firstName');
+ * const getter2 = generatePropertyGetter('config', 'api-key');
+ *
+ * console.log(getter1); // "function getfirstName() { return user.firstName; }"
+ * console.log(getter2); // "function getapikey() { return config['api-key']; }"
+ * ```
+ */
 export declare const handlePropertyName: (name: string, parent: string) => string;
 //# sourceMappingURL=identifiers.d.ts.map

package/esm/typescript/identifiers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"identifiers.d.ts","sourceRoot":"","sources":["../../src/typescript/identifiers.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,SAAS,GAAI,KAAK,MAAM,KAAG,MAEvC,CAAA;AAED,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,EAAE,QAAQ,MAAM,KAAG,MAEjE,CAAA"}
+{"version":3,"file":"identifiers.d.ts","sourceRoot":"","sources":["../../src/typescript/identifiers.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AACH,eAAO,MAAM,SAAS,GAAI,KAAK,MAAM,KAAG,MAEvC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AACH,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,EAAE,QAAQ,MAAM,KAAG,MAEjE,CAAA"}

package/esm/typescript/identifiers.js

@@ -1,7 +1,166 @@
 import { isIdentifierName } from '@babel/helper-validator-identifier';
+/**
+ * Safely formats a key for use in object literals, adding quotes if needed.
+ *
+ * This function determines whether a property key needs to be quoted in JavaScript/TypeScript
+ * object literals based on identifier naming rules. Valid identifiers are left unquoted,
+ * while invalid identifiers (containing spaces, special characters, starting with numbers, etc.)
+ * are wrapped in single quotes.
+ *
+ * @param key - The property key to format
+ * @returns The key as-is if it's a valid identifier, otherwise wrapped in quotes
+ *
+ * @example Valid identifiers (no quotes needed)
+ * ```typescript
+ * import { handleKey } from '@skmtc/core';
+ *
+ * console.log(handleKey('name'));      // 'name'
+ * console.log(handleKey('userName'));  // 'userName'
+ * console.log(handleKey('_private'));  // '_private'
+ * console.log(handleKey('$special'));  // '$special'
+ * ```
+ *
+ * @example Invalid identifiers (quotes added)
+ * ```typescript
+ * console.log(handleKey('first-name'));  // "'first-name'"
+ * console.log(handleKey('2nd-place'));   // "'2nd-place'"
+ * console.log(handleKey('user name'));   // "'user name'"
+ * console.log(handleKey('api-key'));     // "'api-key'"
+ * console.log(handleKey('data.nested')); // "'data.nested'"
+ * ```
+ *
+ * @example Usage in object generation
+ * ```typescript
+ * class ObjectGenerator {
+ *   generateObjectLiteral(properties: Record<string, string>) {
+ *     const props = Object.entries(properties)
+ *       .map(([key, value]) => `${handleKey(key)}: ${value}`)
+ *       .join(', ');
+ *
+ *     return `{ ${props} }`;
+ *   }
+ * }
+ *
+ * const generator = new ObjectGenerator();
+ * const result = generator.generateObjectLiteral({
+ *   'name': 'string',
+ *   'first-name': 'string',
+ *   'age': 'number'
+ * });
+ *
+ * console.log(result);
+ * // { name: string, 'first-name': string, age: number }
+ * ```
+ *
+ * @example TypeScript interface generation
+ * ```typescript
+ * function generateInterface(name: string, properties: Record<string, string>) {
+ *   const props = Object.entries(properties)
+ *     .map(([key, type]) => `  ${handleKey(key)}: ${type};`)
+ *     .join('\n');
+ *
+ *   return `interface ${name} {\n${props}\n}`;
+ * }
+ *
+ * const userInterface = generateInterface('User', {
+ *   'id': 'string',
+ *   'first-name': 'string',
+ *   'last_name': 'string',
+ *   '2fa-enabled': 'boolean'
+ * });
+ *
+ * console.log(userInterface);
+ * // interface User {
+ * //   id: string;
+ * //   'first-name': string;
+ * //   last_name: string;
+ * //   '2fa-enabled': boolean;
+ * // }
+ * ```
+ */
 export const handleKey = (key) => {
     return isIdentifierName(key) ? key : `'${key}'`;
 };
+/**
+ * Safely formats property access, using dot notation or bracket notation as appropriate.
+ *
+ * This function generates the appropriate property access syntax for JavaScript/TypeScript
+ * code. Valid identifiers use dot notation (`parent.property`), while invalid identifiers
+ * use bracket notation (`parent['property']`).
+ *
+ * @param name - The property name to access
+ * @param parent - The parent object expression
+ * @returns Properly formatted property access expression
+ *
+ * @example Valid identifiers (dot notation)
+ * ```typescript
+ * import { handlePropertyName } from '@skmtc/core';
+ *
+ * console.log(handlePropertyName('name', 'user'));      // 'user.name'
+ * console.log(handlePropertyName('firstName', 'user')); // 'user.firstName'
+ * console.log(handlePropertyName('_id', 'document'));   // 'document._id'
+ * console.log(handlePropertyName('$meta', 'data'));     // 'data.$meta'
+ * ```
+ *
+ * @example Invalid identifiers (bracket notation)
+ * ```typescript
+ * console.log(handlePropertyName('first-name', 'user'));  // "user['first-name']"
+ * console.log(handlePropertyName('2nd-place', 'result')); // "result['2nd-place']"
+ * console.log(handlePropertyName('user name', 'form'));   // "form['user name']"
+ * console.log(handlePropertyName('api-key', 'config'));   // "config['api-key']"
+ * ```
+ *
+ * @example Usage in accessor generation
+ * ```typescript
+ * class PropertyAccessor {
+ *   generateGetter(objectName: string, propertyPath: string[]) {
+ *     return propertyPath.reduce((acc, prop) =>
+ *       handlePropertyName(prop, acc), objectName
+ *     );
+ *   }
+ * }
+ *
+ * const accessor = new PropertyAccessor();
+ * const path1 = accessor.generateGetter('data', ['user', 'profile', 'firstName']);
+ * const path2 = accessor.generateGetter('config', ['api-settings', 'retry-count']);
+ *
+ * console.log(path1); // 'data.user.profile.firstName'
+ * console.log(path2); // "config['api-settings']['retry-count']"
+ * ```
+ *
+ * @example Complex object navigation
+ * ```typescript
+ * function generateObjectAccess(base: string, properties: string[]) {
+ *   let result = base;
+ *
+ *   for (const prop of properties) {
+ *     result = handlePropertyName(prop, result);
+ *   }
+ *
+ *   return result;
+ * }
+ *
+ * const access1 = generateObjectAccess('response', ['data', 'user-info', 'name']);
+ * const access2 = generateObjectAccess('settings', ['ui', 'theme', 'darkMode']);
+ *
+ * console.log(access1); // "response.data['user-info'].name"
+ * console.log(access2); // "settings.ui.theme.darkMode"
+ * ```
+ *
+ * @example Function generation
+ * ```typescript
+ * function generatePropertyGetter(objName: string, propName: string) {
+ *   const access = handlePropertyName(propName, objName);
+ *   return `function get${propName.replace(/[^a-zA-Z0-9]/g, '')}() { return ${access}; }`;
+ * }
+ *
+ * const getter1 = generatePropertyGetter('user', 'firstName');
+ * const getter2 = generatePropertyGetter('config', 'api-key');
+ *
+ * console.log(getter1); // "function getfirstName() { return user.firstName; }"
+ * console.log(getter2); // "function getapikey() { return config['api-key']; }"
+ * ```
+ */
 export const handlePropertyName = (name, parent) => {
     return isIdentifierName(name) ? `${parent}.${name}` : `${parent}['${name}']`;
 };

package/esm/typescript/keyValues.d.ts

@@ -1,3 +1,128 @@
 import type { Stringable } from '../dsl/Stringable.js';
+/**
+ * Converts a properties object into a formatted TypeScript object literal string.
+ *
+ * This utility function takes a record of key-value pairs and generates a properly
+ * formatted TypeScript object literal. It automatically filters out empty values
+ * and handles proper spacing and comma placement. If all properties are empty,
+ * it returns the EMPTY constant instead of an empty object.
+ *
+ * The function is particularly useful for generating TypeScript interface properties,
+ * object type definitions, and literal object expressions in code generation scenarios.
+ *
+ * @param properties - Record of property names to their stringable values
+ * @returns Formatted object literal string or EMPTY if no valid properties
+ *
+ * @example Basic object generation
+ * ```typescript
+ * import { keyValues } from '@skmtc/core';
+ *
+ * const props = {
+ *   name: { toString: () => 'string' },
+ *   age: { toString: () => 'number' },
+ *   email: { toString: () => 'string' }
+ * };
+ *
+ * const result = keyValues(props);
+ * console.log(result);
+ * // {name: string,
+ * // age: number,
+ * // email: string}
+ * ```
+ *
+ * @example With empty values filtered
+ * ```typescript
+ * const propsWithEmpty = {
+ *   name: { toString: () => 'string' },
+ *   description: { toString: () => '' }, // Empty, will be filtered
+ *   age: { toString: () => 'number' },
+ *   notes: { toString: () => 'EMPTY' }   // EMPTY constant, will be filtered
+ * };
+ *
+ * const result = keyValues(propsWithEmpty);
+ * console.log(result);
+ * // {name: string,
+ * // age: number}
+ * ```
+ *
+ * @example All empty properties
+ * ```typescript
+ * const emptyProps = {
+ *   description: { toString: () => '' },
+ *   notes: { toString: () => 'EMPTY' }
+ * };
+ *
+ * const result = keyValues(emptyProps);
+ * console.log(result === EMPTY); // true
+ * ```
+ *
+ * @example TypeScript interface generation
+ * ```typescript
+ * class InterfaceGenerator {
+ *   generateInterface(name: string, properties: Record<string, Stringable>) {
+ *     const propsString = keyValues(properties);
+ *
+ *     if (propsString === EMPTY) {
+ *       return `interface ${name} {}`;
+ *     }
+ *
+ *     return `interface ${name} ${propsString}`;
+ *   }
+ * }
+ *
+ * const generator = new InterfaceGenerator();
+ * const userInterface = generator.generateInterface('User', {
+ *   id: { toString: () => 'string' },
+ *   name: { toString: () => 'string' },
+ *   age: { toString: () => 'number' }
+ * });
+ *
+ * console.log(userInterface);
+ * // interface User {id: string,
+ * // name: string,
+ * // age: number}
+ * ```
+ *
+ * @example Object literal generation
+ * ```typescript
+ * function generateObjectLiteral(values: Record<string, string>) {
+ *   const stringableValues = Object.fromEntries(
+ *     Object.entries(values).map(([k, v]) => [k, { toString: () => `'${v}'` }])
+ *   );
+ *
+ *   const result = keyValues(stringableValues);
+ *   return result === EMPTY ? '{}' : result;
+ * }
+ *
+ * const config = generateObjectLiteral({
+ *   apiUrl: 'https://api.example.com',
+ *   timeout: '5000'
+ * });
+ *
+ * console.log(config);
+ * // {apiUrl: 'https://api.example.com',
+ * // timeout: '5000'}
+ * ```
+ *
+ * @example Conditional property inclusion
+ * ```typescript
+ * class ConditionalGenerator {
+ *   generateObjectType(fields: Array<{name: string, type: string, optional?: boolean}>) {
+ *     const properties: Record<string, Stringable> = {};
+ *
+ *     fields.forEach(field => {
+ *       if (field.type) { // Only include fields with types
+ *         const optionalMarker = field.optional ? '?' : '';
+ *         properties[field.name] = {
+ *           toString: () => `${optionalMarker}: ${field.type}`
+ *         };
+ *       }
+ *     });
+ *
+ *     return keyValues(properties);
+ *   }
+ * }
+ * ```
+ */
 export declare const keyValues: (properties: Record<string, Stringable>) => string;
 //# sourceMappingURL=keyValues.d.ts.map

package/esm/typescript/keyValues.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"keyValues.d.ts","sourceRoot":"","sources":["../../src/typescript/keyValues.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAGtD,eAAO,MAAM,SAAS,GAAI,YAAY,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,KAAG,MAUlE,CAAA"}
+{"version":3,"file":"keyValues.d.ts","sourceRoot":"","sources":["../../src/typescript/keyValues.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4HG;AACH,eAAO,MAAM,SAAS,GAAI,YAAY,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,KAAG,MAUlE,CAAA"}

package/esm/typescript/keyValues.js

@@ -1,5 +1,129 @@
 import { EMPTY } from '../dsl/constants.js';
-// Filter out properties with falsy or EMPTY values and return as joined string
+/**
+ * Converts a properties object into a formatted TypeScript object literal string.
+ *
+ * This utility function takes a record of key-value pairs and generates a properly
+ * formatted TypeScript object literal. It automatically filters out empty values
+ * and handles proper spacing and comma placement. If all properties are empty,
+ * it returns the EMPTY constant instead of an empty object.
+ *
+ * The function is particularly useful for generating TypeScript interface properties,
+ * object type definitions, and literal object expressions in code generation scenarios.
+ *
+ * @param properties - Record of property names to their stringable values
+ * @returns Formatted object literal string or EMPTY if no valid properties
+ *
+ * @example Basic object generation
+ * ```typescript
+ * import { keyValues } from '@skmtc/core';
+ *
+ * const props = {
+ *   name: { toString: () => 'string' },
+ *   age: { toString: () => 'number' },
+ *   email: { toString: () => 'string' }
+ * };
+ *
+ * const result = keyValues(props);
+ * console.log(result);
+ * // {name: string,
+ * // age: number,
+ * // email: string}
+ * ```
+ *
+ * @example With empty values filtered
+ * ```typescript
+ * const propsWithEmpty = {
+ *   name: { toString: () => 'string' },
+ *   description: { toString: () => '' }, // Empty, will be filtered
+ *   age: { toString: () => 'number' },
+ *   notes: { toString: () => 'EMPTY' }   // EMPTY constant, will be filtered
+ * };
+ *
+ * const result = keyValues(propsWithEmpty);
+ * console.log(result);
+ * // {name: string,
+ * // age: number}
+ * ```
+ *
+ * @example All empty properties
+ * ```typescript
+ * const emptyProps = {
+ *   description: { toString: () => '' },
+ *   notes: { toString: () => 'EMPTY' }
+ * };
+ *
+ * const result = keyValues(emptyProps);
+ * console.log(result === EMPTY); // true
+ * ```
+ *
+ * @example TypeScript interface generation
+ * ```typescript
+ * class InterfaceGenerator {
+ *   generateInterface(name: string, properties: Record<string, Stringable>) {
+ *     const propsString = keyValues(properties);
+ *
+ *     if (propsString === EMPTY) {
+ *       return `interface ${name} {}`;
+ *     }
+ *
+ *     return `interface ${name} ${propsString}`;
+ *   }
+ * }
+ *
+ * const generator = new InterfaceGenerator();
+ * const userInterface = generator.generateInterface('User', {
+ *   id: { toString: () => 'string' },
+ *   name: { toString: () => 'string' },
+ *   age: { toString: () => 'number' }
+ * });
+ *
+ * console.log(userInterface);
+ * // interface User {id: string,
+ * // name: string,
+ * // age: number}
+ * ```
+ *
+ * @example Object literal generation
+ * ```typescript
+ * function generateObjectLiteral(values: Record<string, string>) {
+ *   const stringableValues = Object.fromEntries(
+ *     Object.entries(values).map(([k, v]) => [k, { toString: () => `'${v}'` }])
+ *   );
+ *
+ *   const result = keyValues(stringableValues);
+ *   return result === EMPTY ? '{}' : result;
+ * }
+ *
+ * const config = generateObjectLiteral({
+ *   apiUrl: 'https://api.example.com',
+ *   timeout: '5000'
+ * });
+ *
+ * console.log(config);
+ * // {apiUrl: 'https://api.example.com',
+ * // timeout: '5000'}
+ * ```
+ *
+ * @example Conditional property inclusion
+ * ```typescript
+ * class ConditionalGenerator {
+ *   generateObjectType(fields: Array<{name: string, type: string, optional?: boolean}>) {
+ *     const properties: Record<string, Stringable> = {};
+ *
+ *     fields.forEach(field => {
+ *       if (field.type) { // Only include fields with types
+ *         const optionalMarker = field.optional ? '?' : '';
+ *         properties[field.name] = {
+ *           toString: () => `${optionalMarker}: ${field.type}`
+ *         };
+ *       }
+ *     });
+ *
+ *     return keyValues(properties);
+ *   }
+ * }
+ * ```
+ */
 export const keyValues = (properties) => {
     const filteredEntries = Object.entries(properties)
         .map(([key, value]) => {