@jahands/dagger-helpers 0.7.2 → 0.7.4

package/src/convert/camel-to-snake.ts

@@ -0,0 +1,135 @@
+// Helper to check if a character is lowercase A-Z
+type IsLower<C extends string> =
+	Lowercase<C> extends Uppercase<C> ? false : C extends Lowercase<C> ? true : false
+// Helper to check if a character is uppercase A-Z
+type IsUpper<C extends string> =
+	Lowercase<C> extends Uppercase<C> ? false : C extends Uppercase<C> ? true : false
+// Helper to check if a character is a digit 0-9
+type IsDigit<C extends string> = C extends `${number}` ? true : false
+
+// Recursive inner helper for CamelToSnakeCase
+// PrevChar tracks the *previous* character from the original string
+type CamelToSnakeInner<S extends string, PrevChar extends string = ''> =
+	// Base case: If the input string S is empty, return an empty string.
+	S extends ''
+		? ''
+		: // Recursive step: If S has content...
+			S extends `${infer First}${infer Rest}`
+			? // --- Logic based on the 'First' character ---
+
+				// 1. Is 'First' an uppercase letter?
+				IsUpper<First> extends true
+				? // 1a. Was 'PrevChar' lowercase or a digit? (Requires underscore)
+					IsLower<PrevChar> extends true
+					? `_${Uppercase<First>}${CamelToSnakeInner<Rest, First>}`
+					: IsDigit<PrevChar> extends true
+						? `_${Uppercase<First>}${CamelToSnakeInner<Rest, First>}`
+						: // 1b. 'PrevChar' was uppercase, symbol, or start. Check for acronym ending.
+							Rest extends `${infer NextChar}${string}` // Look ahead
+							? IsLower<NextChar> extends true // Is the *next* char lowercase?
+								? `_${Uppercase<First>}${CamelToSnakeInner<Rest, First>}` // Yes (e.g., API_Key)
+								: `${Uppercase<First>}${CamelToSnakeInner<Rest, First>}` // No (e.g., HTTP)
+							: // 'First' is the last character or followed by non-lowercase.
+								`${Uppercase<First>}${CamelToSnakeInner<Rest, First>}`
+				: // 2. Is 'First' a digit? (Only checked if not uppercase)
+					IsDigit<First> extends true
+					? // 2a. Was 'PrevChar' a lowercase letter? (Requires underscore)
+						IsLower<PrevChar> extends true
+						? `_${First}${CamelToSnakeInner<Rest, First>}`
+						: // 'PrevChar' was not lowercase (digit, uppercase, symbol, start)
+							`${First}${CamelToSnakeInner<Rest, First>}`
+					: // 3. 'First' must be a lowercase letter or a symbol.
+						//    (Symbols are handled like lowercase here - no underscore needed before them)
+						`${Uppercase<First>}${CamelToSnakeInner<Rest, First>}` // Uppercase letter, append symbol directly
+			: // This case should technically not be reachable if S is not '', but included for completeness.
+				''
+
+/**
+ * Type helper to convert a camelCase/PascalCase string literal type
+ * to an UPPER_SNAKE_CASE string literal type. Handles common cases
+ * including transitions from lower to upper, letters to digits, and basic acronyms.
+ *
+ * Examples:
+ *   'userId' -> 'USER_ID'
+ *   'userName' -> 'USER_NAME'
+ *   'isActive' -> 'IS_ACTIVE'
+ *   'APIKey' -> 'API_KEY'
+ *   'version10' -> 'VERSION_10'
+ *   'apiV2Client' -> 'API_V2_CLIENT'
+ */
+type CamelToSnakeCase<S extends string> = S extends `${infer First}${infer Rest}`
+	? // Uppercase the very first character, then process the rest using the inner helper
+		`${Uppercase<First>}${CamelToSnakeInner<Rest, First>}`
+	: // Handle single character or empty string
+		Uppercase<S>
+
+/**
+ * Converts a camelCase or PascalCase string to UPPER_SNAKE_CASE.
+ * Handles acronyms and numbers within the string.
+ *
+ * **Examples:**
+ * ```
+ *   'helloWorld' -> 'HELLO_WORLD'
+ *   'HelloWorld' -> 'HELLO_WORLD'
+ *   'someAPIKey' -> 'SOME_API_KEY'
+ *   'getHttpResponseCode' -> 'GET_HTTP_RESPONSE_CODE'
+ *   'version10' -> 'VERSION_10' // Fixed
+ *   'version10Alpha' -> 'VERSION_10_ALPHA' // Fixed
+ *   'apiV2Client' -> 'API_V2_CLIENT'
+ *   'releaseV10' -> 'RELEASE_V10'
+ *   'version2Data' -> 'VERSION_2_DATA' // Fixed
+ *   'word' -> 'WORD'
+ *```
+ * @param str The input string in camelCase or PascalCase format.
+ * @returns The converted string in UPPER_SNAKE_CASE format.
+ */
+export function camelToSnake(str: string): string {
+	if (!str) {
+		return ''
+	}
+
+	// The sequence matters:
+	const result = str
+		// 1. Add _ before an uppercase letter that is followed by a lowercase letter,
+		//    but only if the uppercase letter is not the start of the string and
+		//    is preceded by another uppercase letter (handles acronyms like APIKey -> API_Key).
+		.replace(/([A-Z])([A-Z][a-z])/g, '$1_$2')
+		// 2. Add _ before an uppercase letter that is preceded by a lowercase letter or a digit.
+		//    (handles helloWorld -> hello_World, version10Update -> version10_Update, apiV2Client -> api_V2Client)
+		.replace(/([a-z\d])([A-Z])/g, '$1_$2')
+		// 3. Add _ between a lowercase letter and a number.
+		//    (handles version10 -> version_10, but NOT V10 -> V_10 because V is uppercase)
+		.replace(/([a-z])(\d)/g, '$1_$2')
+
+	// Convert the entire result to uppercase
+	return result.toUpperCase()
+}
+
+/**
+ * Converts an object's keys from camelCase/PascalCase to UPPER_SNAKE_CASE.
+ * Provides compile-time type safety for the converted keys based on common patterns.
+ *
+ * @template T The type of the input object.
+ * @param input The object with camelCase/PascalCase keys.
+ * @returns A new object with the same values but UPPER_SNAKE_CASE keys,
+ *          with an inferred type reflecting the key transformation.
+ */
+export function convertToSnake<T extends Record<string, any>>(
+	input: T
+	// Apply the mapped type with key remapping using the type helper
+): { [K in keyof T as CamelToSnakeCase<K & string>]: T[K] } {
+	const output: any = {} // Initialize as 'any' or '{}'
+
+	for (const key in input) {
+		if (Object.prototype.hasOwnProperty.call(input, key)) {
+			const snakeCaseKey = camelToSnake(key) // Runtime conversion
+			output[snakeCaseKey] = input[key]
+		}
+	}
+
+	// Type assertion: We trust the runtime `camelToSnake` logic produces keys
+	// matching the structure defined by the `CamelToSnakeCase` type helper.
+	// This is needed because TS can't perfectly verify the runtime logic
+	// against the complex type-level logic for all possible inputs.
+	return output as { [K in keyof T as CamelToSnakeCase<K & string>]: T[K] }
+}

package/src/convert/snake-to-camel.spec.ts

@@ -0,0 +1,221 @@
+import { describe, expect, it, test } from 'vitest'
+
+import { convertToCamel, snakeToCamel } from './snake-to-camel.js'
+
+// --- Tests for snakeToCamel ---
+describe('snakeToCamel', () => {
+	// Test cases using test.each for various formats
+	test.each([
+		// Basic cases
+		{ input: 'HELLO_WORLD', expected: 'helloWorld' },
+		{ input: 'SOME_API_KEY', expected: 'someApiKey' },
+		{ input: 'USER_ID', expected: 'userId' },
+		{ input: 'REQUEST_URL_PATH', expected: 'requestUrlPath' },
+
+		// All caps single word
+		{ input: 'WORD', expected: 'word' },
+		{ input: 'TOKEN', expected: 'token' },
+
+		// Lowercase single word (should ideally remain lowercase, current logic lowercases first char)
+		{ input: 'word', expected: 'word' },
+		{ input: 'token', expected: 'token' },
+
+		// Already camelCase (should ideally remain camelCase, current logic lowercases first char)
+		{ input: 'helloWorld', expected: 'helloWorld' },
+		{ input: 'someApiKey', expected: 'someApiKey' },
+
+		// PascalCase (should convert to camelCase)
+		{ input: 'HelloWorld', expected: 'helloWorld' },
+		{ input: 'SomeApiKey', expected: 'someApiKey' },
+
+		// Leading underscores
+		{ input: '_LEADING_UNDERSCORE', expected: 'leadingUnderscore' },
+		{ input: '__DOUBLE_LEADING', expected: 'doubleLeading' },
+		{ input: '_word', expected: 'word' }, // Single word with leading underscore
+
+		// Trailing underscores
+		{ input: 'TRAILING_UNDERSCORE_', expected: 'trailingUnderscore' },
+		{ input: 'DOUBLE_TRAILING__', expected: 'doubleTrailing' },
+		{ input: 'word_', expected: 'word' }, // Single word with trailing underscore
+
+		// Consecutive underscores
+		{ input: 'DOUBLE__UNDERSCORE', expected: 'doubleUnderscore' },
+		{ input: 'TRIPLE___UNDERSCORE', expected: 'tripleUnderscore' },
+		{ input: 'LEADING___MIDDLE__TRAILING_', expected: 'leadingMiddleTrailing' },
+
+		// Mixed case input parts
+		{ input: 'Mixed_Case_Input', expected: 'mixedCaseInput' },
+		{ input: 'another_Mixed_CASE', expected: 'anotherMixedCase' },
+
+		// Keys with numbers
+		{ input: 'KEY_123', expected: 'key123' },
+		{ input: 'VERSION_1_0', expected: 'version10' },
+		{ input: 'API_V2_KEY', expected: 'apiV2Key' },
+		{ input: '123_STARTING_NUMBER', expected: '123StartingNumber' }, // Starts with number
+
+		// Edge cases
+		{ input: '', expected: '' }, // Empty string
+		{ input: '_', expected: '' }, // Single underscore
+		{ input: '__', expected: '' }, // Double underscore
+		{ input: '___', expected: '' }, // Triple underscore
+		{ input: '_A_', expected: 'a' }, // Underscores around single letter
+		{ input: 'A', expected: 'a' }, // Single uppercase letter
+		{ input: 'a', expected: 'a' }, // Single lowercase letter
+		{ input: '1', expected: '1' }, // Single number as string
+		{ input: '123', expected: '123' }, // Multiple numbers as string
+	])('should convert "$input" to "$expected"', ({ input, expected }) => {
+		expect(snakeToCamel(input)).toBe(expected)
+	})
+})
+
+// --- Tests for convertToCamel ---
+describe('convertToCamel', () => {
+	it('should convert keys of a basic object', () => {
+		const input = {
+			FIRST_NAME: 'John',
+			LAST_NAME: 'Doe',
+			USER_ID: 123,
+		}
+		const expected = {
+			firstName: 'John',
+			lastName: 'Doe',
+			userId: 123,
+		}
+		const result = convertToCamel(input)
+		expect(result).toStrictEqual(expected)
+		// Type check (compile time): result should have the correct inferred type
+		expect(result.firstName).toBe('John')
+		expect(result.userId).toBe(123)
+		// expect(result.FIRST_NAME).toBeUndefined(); // This would be a TS error
+	})
+
+	it('should handle various value types correctly', () => {
+		const input = {
+			STRING_VALUE: 'hello',
+			NUMBER_VALUE: 42,
+			BOOLEAN_TRUE: true,
+			BOOLEAN_FALSE: false,
+			NULL_VALUE: null,
+			UNDEFINED_VALUE: undefined,
+			ARRAY_VALUE: [1, 'two', { NESTED_KEY: true }],
+			NESTED_OBJECT: {
+				INNER_KEY_1: 'value1',
+				INNER_KEY_2: 99,
+			},
+		}
+		const expected = {
+			stringValue: 'hello',
+			numberValue: 42,
+			booleanTrue: true,
+			booleanFalse: false,
+			nullValue: null,
+			undefinedValue: undefined,
+			arrayValue: [1, 'two', { NESTED_KEY: true }], // Note: nested object keys are NOT converted
+			nestedObject: {
+				INNER_KEY_1: 'value1', // Note: nested object keys are NOT converted
+				INNER_KEY_2: 99,
+			},
+		}
+		const result = convertToCamel(input)
+		expect(result).toStrictEqual(expected)
+		// Check specific inferred types/values
+		expect(result.arrayValue).toEqual([1, 'two', { NESTED_KEY: true }])
+		expect(result.nestedObject.INNER_KEY_1).toBe('value1')
+		expect(result.nullValue).toBeNull()
+		expect(result.undefinedValue).toBeUndefined()
+	})
+
+	it('should return an empty object for an empty input object', () => {
+		const input = {}
+		const expected = {}
+		expect(convertToCamel(input)).toStrictEqual(expected)
+	})
+
+	it('should handle keys with leading/trailing/multiple underscores', () => {
+		const input = {
+			_LEADING_KEY: 'val1',
+			TRAILING_KEY_: 'val2',
+			DOUBLE__KEY: 'val3',
+			__BOTH__: 'val4',
+		}
+		const expected = {
+			leadingKey: 'val1',
+			trailingKey: 'val2',
+			doubleKey: 'val3',
+			both: 'val4',
+		}
+		const result = convertToCamel(input)
+		expect(result).toStrictEqual(expected)
+	})
+
+	it('should handle keys that are already camelCase or mixed', () => {
+		const input = {
+			alreadyCamel: 'value1',
+			PascalCaseKey: 'value2', // Will become pascalCaseKey
+			MIXED_key_STYLE: 'value3',
+		}
+		const expected = {
+			alreadyCamel: 'value1', // Stays camelCase as no underscores
+			pascalCaseKey: 'value2', // First letter lowercased
+			mixedKeyStyle: 'value3',
+		}
+		const result = convertToCamel(input)
+		expect(result).toStrictEqual(expected)
+	})
+
+	it('should handle keys with numbers', () => {
+		const input = {
+			KEY_1: 1,
+			KEY_2_PART: 2,
+			VERSION_10X: 'v10',
+			_1_START: 'start',
+		}
+		const expected = {
+			key1: 1,
+			key2Part: 2,
+			version10x: 'v10',
+			'1Start': 'start', // Note: snakeToCamel logic produces this
+		}
+		const result = convertToCamel(input)
+		expect(result).toStrictEqual(expected)
+	})
+
+	it('should not include properties from the prototype chain', () => {
+		const proto = { PROTO_KEY: 'protoValue' }
+		const input = Object.create(proto)
+		input.OWN_KEY = 'ownValue'
+		input.ANOTHER_OWN = 'another'
+
+		const expected = {
+			ownKey: 'ownValue',
+			anotherOwn: 'another',
+		}
+		const result = convertToCamel(input)
+		expect(result).toStrictEqual(expected)
+		// Ensure proto property isn't present (even in camelCase)
+		expect((result as any).protoKey).toBeUndefined()
+	})
+
+	it('should produce a correctly typed object (compile-time check)', () => {
+		const input = {
+			API_TOKEN: 'xyz',
+			USER_COUNT: 100,
+		} as const // Use 'as const' for more precise type inference if needed
+
+		const result = convertToCamel(input)
+
+		// These lines check the type inference at compile time.
+		// If you hover over `result` or try to access invalid properties,
+		// TypeScript/your IDE should show the correct inferred type/errors.
+		const token: string = result.apiToken
+		const count: number = result.userCount
+
+		expect(token).toBe('xyz')
+		expect(count).toBe(100)
+
+		// @ts-expect-error
+		const _invalid: string = result.API_TOKEN
+		// @ts-expect-error
+		const _nonExistent: number = result.someOtherKey
+	})
+})

package/src/convert/snake-to-camel.ts

@@ -0,0 +1,101 @@
+/**
+ * Helper type to capitalize the first letter of a string literal type.
+ * e.g., 'hello' -> 'Hello'
+ */
+type CapitalizeString<S extends string> = S extends `${infer First}${infer Rest}`
+	? `${Uppercase<First>}${Rest}`
+	: S
+
+/**
+ * Recursively transforms a snake_case string literal type to camelCase.
+ * e.g., 'SOME_API_KEY' -> 'someApiKey'
+ *       'HELLO_WORLD'  -> 'helloWorld'
+ *       'WORD'         -> 'word'
+ */
+type SnakeToCamelCase<S extends string> = S extends `${infer T}_${infer U}`
+	? `${Lowercase<T>}${CapitalizeString<SnakeToCamelCase<U>>}` // Lowercase first part, capitalize and recurse on the rest
+	: Lowercase<S> // Base case: No underscore, just lowercase the whole thing
+
+/**
+ * Converts a string from snake_case, UPPER_SNAKE_CASE, PascalCase,
+ * or ALL_CAPS to camelCase at runtime.
+ * If the string is already camelCase or lowercase, it remains unchanged.
+ *
+ * @param str The input string in snake_case format.
+ * @returns The converted string in camelCase format.
+ */
+export function snakeToCamel(str: string): string {
+	if (!str) {
+		return ''
+	}
+
+	// Case 1: String contains underscores (snake_case)
+	if (str.includes('_')) {
+		let result = ''
+		const parts = str.split('_')
+		for (let i = 0; i < parts.length; i++) {
+			const part = parts[i]
+			if (part) {
+				// Skip empty parts from multiple underscores
+				if (result.length === 0) {
+					// First non-empty part: lowercase the whole part
+					result += part.toLowerCase()
+				} else {
+					// Subsequent non-empty parts: capitalize first letter, rest lowercase
+					result += part[0]!.toUpperCase() + part.slice(1).toLowerCase()
+				}
+			}
+		}
+		// Handle case like "_SOME_WORD_" -> "someWord"
+		// If the first character of the original string was '_' and result is empty,
+		// it means the string was only underscores, return ''
+		// If the first part was empty ('_WORD'), result starts lowercase correctly.
+		return result
+	}
+
+	// Case 2: String does NOT contain underscores
+	// Check if it's ALL_CAPS (allowing for numbers)
+	const isAllCaps = /^[A-Z0-9]+$/.test(str)
+	if (isAllCaps) {
+		// e.g., "WORD", "TOKEN123" -> "word", "token123"
+		return str.toLowerCase()
+	}
+
+	// Check if it's PascalCase or already camelCase/lowercase
+	// If the first letter is already lowercase, assume it's camelCase or lowercase
+	if (str[0] === str[0]!.toLowerCase()) {
+		// e.g., "helloWorld", "word" -> stays the same
+		return str
+	}
+
+	// Otherwise, assume it's PascalCase: Lowercase only the first character
+	// e.g., "HelloWorld", "SomeValue" -> "helloWorld", "someValue"
+	return str[0]!.toLowerCase() + str.slice(1)
+}
+
+/**
+ * Converts an object's keys from snake_case or UPPER_SNAKE_CASE to camelCase.
+ * The return type precisely maps the input keys to their camelCase versions.
+ *
+ * @template T The type of the input object, expected to have string keys.
+ * @param input The object with snake_case keys.
+ * @returns A new object with the same values but camelCase keys, with a specific inferred type.
+ */
+export function convertToCamel<T extends Record<string, any>>(
+	input: T
+): { [K in keyof T as SnakeToCamelCase<K & string>]: T[K] } {
+	const output: any = {}
+
+	for (const key in input) {
+		if (Object.prototype.hasOwnProperty.call(input, key)) {
+			const camelCaseKey = snakeToCamel(key)
+			output[camelCaseKey] = input[key]
+		}
+	}
+
+	// We use a type assertion here. While our runtime logic creates the correct
+	// shape, TypeScript's analysis within the loop isn't powerful enough to
+	// automatically verify that 'output' perfectly matches the complex mapped type.
+	// The return type annotation guarantees the type for the caller.
+	return output as { [K in keyof T as SnakeToCamelCase<K & string>]: T[K] }
+}