# converter — Type and Case Conversion

> `import { addZero, nbrToCurrency, s2cCase, c2sCase, capital2cCase, objectC2Scase, objectS2Ccase, objectCapital2Ccase, toNumber, toBoolean, toObj, toArray } from 'puffy-core/converter'`
> CJS: `const { converter: { addZero, nbrToCurrency, s2cCase, c2sCase, capital2cCase, objectC2Scase, objectS2Ccase, objectCapital2Ccase, toNumber, toBoolean, toObj, toArray } } = require('puffy-core')`
> Also available in snake_case: `nbr_to_currency`, `s2c_case`, `c2s_case`, `capital2c_case`, `object_c2s_case`, `object_s2c_case`, `object_capital2c_case`, `add_zero`, `to_number`, `to_boolean`, `to_obj`, `to_array`

---

## addZero

Left-pads a number with zeros to reach a target length.

### Signature

```
addZero(nbr: number|string, length: number) → string
```

### Examples

```js
addZero(123, 10)   // '0000000123'
addZero(123, 3)    // '123'       — already at target length
addZero(123, 2)    // '123'       — longer than target, returned as-is
addZero(5, 3)      // '005'
```

---

## nbrToCurrency

Formats a number as a currency string with symbol, thousands separators, and 2 decimal places.

### Signature

```
nbrToCurrency(nbr: number, symbol?: string) → string
```

Default symbol: `'$'`

Accepted symbol values: `'$'`, `'dollar'`, `'€'`, `'euro'`, `'¥'`, `'yen'`, `'yuan'`, `'£'`, `'pound'`

### Examples

```js
nbrToCurrency(123)            // '$123.00'
nbrToCurrency(123, '$')       // '$123.00'
nbrToCurrency(123, 'dollar')  // '$123.00'
nbrToCurrency(123, 'euro')    // '€123.00'
nbrToCurrency(123, '€')       // '€123.00'
nbrToCurrency(123, 'yen')     // '¥123.00'
nbrToCurrency(123, 'yuan')    // '¥123.00'
nbrToCurrency(123, 'pound')   // '£123.00'
nbrToCurrency(1234567.89)     // '$1,234,567.89'
nbrToCurrency(123.936)        // '$123.94'  — rounds to 2 decimals
nbrToCurrency(null)           // '$0.00'    — non-numeric defaults to 0
```

---

## String Case Conversion

### s2cCase — Snake case to camelCase

```
s2cCase(str: string) → string
```

```js
s2cCase('hello_world')     // 'helloWorld'
s2cCase('my_long_name')    // 'myLongName'
s2cCase('already')         // 'already'
```

### c2sCase — CamelCase to snake_case

```
c2sCase(str: string) → string
```

```js
c2sCase('helloWorld')      // 'hello_world'
c2sCase('myLongName')      // 'my_long_name'
c2sCase('already')         // 'already'
```

### capital2cCase — CapitalCase to camelCase

```
capital2cCase(str: string) → string
```

```js
capital2cCase('FirstName')  // 'firstName'
capital2cCase('HelloWorld') // 'helloWorld'
```

---

## Object Key Case Conversion

Recursively convert all keys in an object (including nested objects and arrays of objects).

### Signatures

```
objectC2Scase(obj: Object) → Object    // camelCase keys → snake_case keys
objectS2Ccase(obj: Object) → Object    // snake_case keys → camelCase keys
objectCapital2Ccase(obj: Object) → Object  // CapitalCase keys → camelCase keys
```

### Examples

```js
objectC2Scase({ firstName:'Nic', lastName:'Dao' })
// { first_name: 'Nic', last_name: 'Dao' }

objectS2Ccase({ first_name:'Nic', last_name:'Dao' })
// { firstName: 'Nic', lastName: 'Dao' }

// Recursive — handles nested objects and arrays
objectC2Scase({
	userName: 'Nic',
	contactInfo: {
		emailAddress: 'nic@example.com',
		phoneNumbers: [{ mobileNumber: '123' }]
	}
})
// {
//   user_name: 'Nic',
//   contact_info: {
//     email_address: 'nic@example.com',
//     phone_numbers: [{ mobile_number: '123' }]
//   }
// }
```

GOTCHA: Date objects are skipped during recursion (treated as leaf values, not objects to recurse into). This is intentional.

---

## Type Conversion

All type converters handle null/undefined gracefully and support an optional default value.

### toNumber

```
toNumber(value: any, _default?: any) → number|null
```

```js
toNumber('123')         // 123
toNumber('12.5')        // 12.5
toNumber('abc')         // null
toNumber('abc', 0)      // 0       — _default returned on failure
toNumber(null)          // 0
toNumber(undefined)     // 0
toNumber(true)          // 1
toNumber(false)         // 0
```

### toBoolean

```
toBoolean(value: any, _default?: any) → boolean
```

```js
toBoolean('true')       // true
toBoolean('1')          // true
toBoolean('false')      // false
toBoolean('0')          // false
toBoolean(1)            // true
toBoolean(0)            // false
toBoolean(null)         // false
toBoolean(undefined)    // false
toBoolean({})           // true
toBoolean('maybe')      // undefined  — not a recognized boolean string
toBoolean('maybe', false) // false    — _default returned
```

### toObj

```
toObj(value: any, _default?: any) → Object|null
```

```js
toObj('{"a":1}')        // { a: 1 }
toObj({ a:1 })          // { a: 1 }  — objects returned as-is
toObj('invalid', {})    // {}        — _default on parse error
toObj(null)             // null
```

### toArray

```
toArray(value: any, _default?: any) → Array
```

```js
toArray('[1,2,3]')       // [1, 2, 3]
toArray([1,2])           // [1, 2]   — arrays returned as-is
toArray('invalid', [])   // []       — _default on parse error
toArray(null)            // []
toArray('{"a":1}')       // [{"a":1}] — non-array JSON wrapped in array
```