json-shifter
v0.2.5
Published
A blazingly fast, declarative data transformer for JSON
Maintainers
jahzielcabreraReadme
json-shifter
A blazingly fast, 100% declarative JSON data transformer. Transform any data structure without writing code - just declare what you want.
✨ Works in Browser AND Node.js - Hybrid package with WebAssembly + Native bindings!
Installation
npm install json-shifterNo dependencies required! The package automatically uses the best available engine:
- 🌐 Browser: WebAssembly (WASM) - Fast, secure, runs anywhere
- ⚡ Node.js: Native NAPI addon (fastest) or CLI binary (fallback)
Quick Start
Browser (ES Modules)
<!DOCTYPE html>
<html>
<body>
<script type="module">
import { transform } from 'json-shifter';
const input = {
order_id: '12345',
amount_cents: 29900,
customer_email: ' [email protected] '
};
const config = {
version: '1.0',
mapping: {
id: { source: 'order_id', type: 'string' },
amount_usd: {
source: 'amount_cents',
divide: 100,
type: 'currency',
decimals: 2
},
email: { source: 'customer_email', type: 'email' }
}
};
const result = await transform(input, config);
console.log(result);
// { id: '12345', amount_usd: 299.00, email: '[email protected]' }
</script>
</body>
</html>Node.js (CommonJS)
const { transform } = require('json-shifter');
const input = {
order_id: '12345',
amount_cents: 29900,
customer_email: ' [email protected] '
};
const config = {
version: '1.0',
mapping: {
id: { source: 'order_id', type: 'string' },
amount_usd: {
source: 'amount_cents',
divide: 100,
type: 'currency',
decimals: 2
},
email: { source: 'customer_email', type: 'email' }
}
};
const result = await transform(input, config);
console.log(result);TypeScript
import { transform, TransformConfig } from 'json-shifter';
const config: TransformConfig = {
version: '1.0',
mapping: {
price: {
source: 'price_cents',
divide: 100,
type: 'currency'
}
}
};
const result = await transform({ price_cents: 2999 }, config);API
transform(input, config)
Transform a single object.
const result = await transform(input, config);transformBatch(inputs, config)
Transform an array of objects (batch processing with parallel support in Node.js).
const results = await transformBatch([input1, input2, input3], config);transformFile(inputPath, configPath) (Node.js only)
Transform data from files.
const result = await transformFile('./input.json', './config.json');validateConfig(config)
Validate a configuration.
try {
await validateConfig(config);
console.log('✓ Config is valid');
} catch (error) {
console.error('Config error:', error.message);
}generateConfig(input)
Generate a sample configuration from input data.
const sampleInput = {
name: 'John',
age: 30,
email: '[email protected]'
};
const config = await generateConfig(sampleInput);CLI Usage
The package also provides a CLI:
# Transform using files
npx json-shifter input.json -c config.json -o output.json
# Pretty print
npx json-shifter input.json -c config.json --pretty
# Validate config
npx json-shifter --validate -c config.json
# Generate config from input
npx json-shifter generate-config input.jsonPerformance Modes
The package automatically detects the best execution mode:
| Environment | Mode | Speed | Notes | |------------|------|-------|-------| | Browser | WASM | ⚡⚡⚡ | ~2MB, runs in any browser | | Node.js | NAPI | ⚡⚡⚡⚡ | Native addon (fastest) | | Node.js | CLI | ⚡⚡ | Fallback, spawns binary |
You can check which mode is being used:
import { initialize } from 'json-shifter';
const mode = await initialize();
console.log('Using:', mode); // 'wasm', 'napi', or 'cli'Common Patterns
Currency Conversion
{
price_usd: {
source: 'price_cents',
divide: 100,
type: 'currency',
decimals: 2
}
}Email Normalization
{
email: {
source: 'raw_email',
type: 'email' // Auto trims and lowercases
}
}Field Joining & Case Operations
{
full_name: {
join: ['first_name', 'last_name'],
separator: ' ',
case: 'title' // 'lower' | 'upper' | 'title' | 'camel' | 'snake' | 'kebab' | 'pascal' | 'constant'
},
phone_digits: {
source: 'phone',
extract_digits: true // "+1 (555) 123-4567" → "15551234567"
},
summary: {
source: 'description',
max_length: 100,
ellipsis: '...'
}
}Boolean Operations
{
is_high_value: {
source: 'amount',
greater_than: 1000
},
has_discount: {
source: 'description',
contains: 'sale'
},
is_valid_email: {
source: 'email',
matches: '^[\\w-\\.]+@([\\w-]+\\.)+[\\w-]{2,4}$'
}
}Array Operations
{
total_quantity: {
source: 'items[].quantity',
sum: true
},
last_item: {
source: 'items',
at: -1 // Supports negative indices
},
flat_tags: {
source: 'nested_tags',
flatten: true
}
}Math Operations
{
total: {
add: ['subtotal', 'tax', 'shipping'],
type: 'currency',
decimals: 2
},
squared: {
source: 'value',
power: 2
},
clamped: {
source: 'value',
min: 1,
max: 100
}
}Type System
Supported types with automatic normalization:
string- Trims whitespace, handles nullnumber- Parses strings, currency formats, comma separatorsboolean- Handles yes/no, true/false, 1/0, on/offdate- Auto-detects formats, timestampscurrency- Removes symbols, rounds decimalsemail- Trims and lowercasesurl- Normalizes, adds protocolphone- Extracts digitsarray- Ensures array (wraps single values)object- Ensures object
Browser Bundle Size
| Build | Size (gzip) | Notes | |-------|-------------|-------| | WASM | ~600KB | One-time download, cached | | Full package | ~1.2MB | Includes all modes |
Version 0.2.0 - What's New 🎉
🌐 Hybrid Browser + Node.js Support!
- WebAssembly for browsers
- NAPI native addon for Node.js (fastest)
- CLI binary fallback
- Same API everywhere
26 New Operations
- String:
extract_digits,extract_letters,max_length,split,collapse_whitespace,remove_newlines,remove - Math:
modulo,power,abs,round - Boolean:
not_equals,greater_than,less_than,contains,starts_with,ends_with,matches(regex) - Array:
at,flatten,compact,slice,min,max - Case: Full support for
title,camel,snake,kebab,pascal,constant
Completion Status
81% Complete - 60 out of 74 operations fully implemented!
Documentation
For complete documentation and examples:
Performance
Built in Rust for maximum performance:
- Process thousands of records per second
- Parallel batch processing (Node.js)
- Near-native speed in browsers via WASM
License
MIT
Contributing
Contributions welcome! Focus areas:
- Completing remaining operations
- Performance optimization
- Documentation and examples