@covenant-rpc/ion 1.0.3

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @covenant-rpc/ion
+
+## 1.0.3
+
+### Patch Changes
+
+- 8061179: Initial publish
+
+## 1.0.2
+
+### Patch Changes
+
+- Fix all packages

package/README.md

@@ -0,0 +1,101 @@
+
+
+# `ION`
+
+`ION` - Isomorphic Object Notation
+
+## Purpose
+
+`ION` is a `JSON` like object serialization format. If given the following code:
+
+```ts
+function isomorphicSerialize(obj: any) {
+    const serialized = ION.stringify(obj);
+    const deserialized = ION.parse(obj);
+}
+```
+
+It guarantees that either:
+- `ION.stringify` throws an error
+- `deserialized` and `obj` are identical objects
+
+
+`JSON` fails in various circumstances at this:
+- `Date`s become strings
+- `undefined` becomes null
+- `Symbol`s are omitted
+- `NaN`, `Infinity`, and `-Infinity` become null
+- Sets and maps become `{}`
+
+In cases where something can't be perfectly recreated from parsing, ION will throw an error.
+
+## Performance
+
+ION is optimized for performance while maintaining type safety guarantees:
+
+**Stringify Performance:**
+- Small objects: ~3.2x slower than JSON
+- Medium objects: ~3.5x slower than JSON
+- Large arrays (100 items): ~1.8x slower than JSON
+- String-heavy data: ~2.1x slower than JSON
+
+**Parse Performance:**
+- Small objects: ~8.6x slower than JSON
+- Medium objects: ~5.6x slower than JSON
+- Large arrays (100 items): ~5.5x slower than JSON
+- String-heavy data: ~2.4x slower than JSON
+
+**Average:** ION stringify is ~2.2x slower and parse is ~5.7x slower than JSON, while providing complete type preservation and safety guarantees that JSON cannot offer.
+
+
+## Syntax
+
+
+`ION` is a superset of `JSON`. Any valid `JSON` is valid `ION`, although not all objects are translated exactly the same.
+
+
+```ion
+{
+    "string": "hello",
+    "number": 123,
+    "array": [
+        {
+            "name": null,
+            "boolean": true,
+        }
+    ]
+}
+```
+
+`JSON` has support for several types: `boolean`, `number`, `string`, `object`, and `array`. `ION` adds a couple more:
+- `Infinity`
+- `-Infinity`
+- `NaN`
+- `Date`
+- `Map`
+- `Set`
+
+Note: `WeakMap` and `WeakSet` cannot be serialized and will throw an error if encountered.
+
+
+If an object has any `undefined` properties, they are simply omitted. These advanced properties look like:
+
+```ion
+{
+    "date": date:2026-01-27T15:30:00Z,
+    "not-a-number": NaN,
+    "infinity": Infinity,
+    "negativeInf": -Infinity,
+    "someMap": map {
+        "property": 1,
+        "another": 2
+    },
+    "someSet": set {
+        "a",
+        "b"
+    }
+}
+```
+
+
+

package/benchmark-types.ts

@@ -0,0 +1,184 @@
+import ION from './index.ts';
+
+console.log('='.repeat(100));
+console.log('ION vs JSON: Type Preservation Comparison');
+console.log('='.repeat(100));
+
+// Test 1: Dates
+console.log('\n1. Date Handling');
+console.log('-'.repeat(100));
+const dateObj = { timestamp: new Date('2026-01-27T15:30:00Z'), name: 'Event' };
+
+const jsonDate = JSON.parse(JSON.stringify(dateObj));
+const ionDate = ION.parse(ION.stringify(dateObj)) as typeof dateObj;
+
+console.log('Original:', dateObj);
+console.log('JSON:    ', jsonDate);
+console.log('  - timestamp type:', typeof jsonDate.timestamp);
+console.log('  - timestamp value:', jsonDate.timestamp);
+console.log('ION:     ', ionDate);
+console.log('  - timestamp type:', typeof ionDate.timestamp);
+console.log('  - timestamp instanceof Date:', ionDate.timestamp instanceof Date);
+
+// Test 2: NaN and Infinity
+console.log('\n2. Special Numbers (NaN, Infinity)');
+console.log('-'.repeat(100));
+const specialNumbers = {
+  nan: NaN,
+  infinity: Infinity,
+  negInfinity: -Infinity,
+  normal: 42,
+};
+
+const jsonSpecial = JSON.parse(JSON.stringify(specialNumbers));
+const ionSpecial = ION.parse(ION.stringify(specialNumbers)) as typeof specialNumbers;
+
+console.log('Original:', specialNumbers);
+console.log('JSON:    ', jsonSpecial);
+console.log('  - nan is NaN:', Number.isNaN(jsonSpecial.nan));
+console.log('  - infinity is Infinity:', jsonSpecial.infinity === Infinity);
+console.log('ION:     ', ionSpecial);
+console.log('  - nan is NaN:', Number.isNaN(ionSpecial.nan));
+console.log('  - infinity is Infinity:', ionSpecial.infinity === Infinity);
+console.log('  - negInfinity is -Infinity:', ionSpecial.negInfinity === -Infinity);
+
+// Test 3: Maps
+console.log('\n3. Map Handling');
+console.log('-'.repeat(100));
+const mapObj = {
+  config: new Map<string | number, string | number>([
+    ['theme', 'dark'],
+    ['fontSize', 14],
+    [123, 'numeric key'],
+  ]),
+};
+
+const jsonMap = JSON.parse(JSON.stringify(mapObj));
+const ionMap = ION.parse(ION.stringify(mapObj)) as typeof mapObj;
+
+console.log('Original:', mapObj);
+console.log('  - config instanceof Map:', mapObj.config instanceof Map);
+console.log('  - config.get("theme"):', mapObj.config.get('theme'));
+console.log('JSON:    ', jsonMap);
+console.log('  - config instanceof Map:', jsonMap.config instanceof Map);
+console.log('  - config type:', typeof jsonMap.config);
+console.log('ION:     ', ionMap);
+console.log('  - config instanceof Map:', ionMap.config instanceof Map);
+console.log('  - config.get("theme"):', ionMap.config.get('theme'));
+console.log('  - config.get(123):', ionMap.config.get(123));
+
+// Test 4: Sets
+console.log('\n4. Set Handling');
+console.log('-'.repeat(100));
+const setObj = {
+  tags: new Set(['javascript', 'typescript', 'bun']),
+  count: 3,
+};
+
+const jsonSet = JSON.parse(JSON.stringify(setObj));
+const ionSet = ION.parse(ION.stringify(setObj)) as typeof setObj;
+
+console.log('Original:', setObj);
+console.log('  - tags instanceof Set:', setObj.tags instanceof Set);
+console.log('  - tags.has("typescript"):', setObj.tags.has('typescript'));
+console.log('JSON:    ', jsonSet);
+console.log('  - tags instanceof Set:', jsonSet.tags instanceof Set);
+console.log('  - tags type:', typeof jsonSet.tags);
+console.log('ION:     ', ionSet);
+console.log('  - tags instanceof Set:', ionSet.tags instanceof Set);
+console.log('  - tags.has("typescript"):', ionSet.tags.has('typescript'));
+
+// Test 5: undefined properties
+console.log('\n5. undefined Handling');
+console.log('-'.repeat(100));
+const undefinedObj = {
+  name: 'Alice',
+  age: undefined,
+  email: 'alice@example.com',
+  phone: undefined,
+};
+
+const jsonUndefined = JSON.parse(JSON.stringify(undefinedObj));
+const ionUndefined = ION.parse(ION.stringify(undefinedObj)) as Record<string, unknown>;
+
+console.log('Original:', undefinedObj);
+console.log('  - has "age" property:', 'age' in undefinedObj);
+console.log('  - has "phone" property:', 'phone' in undefinedObj);
+console.log('JSON:    ', jsonUndefined);
+console.log('  - has "age" property:', 'age' in jsonUndefined);
+console.log('  - has "phone" property:', 'phone' in jsonUndefined);
+console.log('ION:     ', ionUndefined);
+console.log('  - has "age" property:', 'age' in ionUndefined);
+console.log('  - has "phone" property:', 'phone' in ionUndefined);
+
+// Test 6: Complex real-world scenario
+console.log('\n6. Real-World Scenario: API Response with Mixed Types');
+console.log('-'.repeat(100));
+const apiResponse = {
+  user: {
+    id: 123,
+    name: 'Alice',
+    lastLogin: new Date('2026-01-27T15:30:00Z'),
+    score: NaN, // not yet calculated
+    preferences: new Map<string, string | boolean>([
+      ['theme', 'dark'],
+      ['notifications', true],
+    ]),
+    roles: new Set(['admin', 'user']),
+    optionalField: undefined,
+  },
+  metadata: {
+    requestTime: new Date('2026-01-27T15:35:00Z'),
+    version: '1.0.0',
+  },
+};
+
+console.log('\nOriginal object:');
+console.log('  - user.lastLogin instanceof Date:', apiResponse.user.lastLogin instanceof Date);
+console.log('  - user.score is NaN:', Number.isNaN(apiResponse.user.score));
+console.log('  - user.preferences instanceof Map:', apiResponse.user.preferences instanceof Map);
+console.log('  - user.roles instanceof Set:', apiResponse.user.roles instanceof Set);
+console.log('  - user has "optionalField":', 'optionalField' in apiResponse.user);
+
+const jsonApi = JSON.parse(JSON.stringify(apiResponse));
+console.log('\nJSON round-trip:');
+console.log('  - user.lastLogin instanceof Date:', jsonApi.user.lastLogin instanceof Date);
+console.log('  - user.lastLogin type:', typeof jsonApi.user.lastLogin);
+console.log('  - user.score is NaN:', Number.isNaN(jsonApi.user.score));
+console.log('  - user.score value:', jsonApi.user.score);
+console.log('  - user.preferences instanceof Map:', jsonApi.user.preferences instanceof Map);
+console.log('  - user.roles instanceof Set:', jsonApi.user.roles instanceof Set);
+console.log('  - user has "optionalField":', 'optionalField' in jsonApi.user);
+
+const ionApi = ION.parse(ION.stringify(apiResponse)) as typeof apiResponse;
+console.log('\nION round-trip:');
+console.log('  - user.lastLogin instanceof Date:', ionApi.user.lastLogin instanceof Date);
+console.log('  - user.score is NaN:', Number.isNaN(ionApi.user.score));
+console.log('  - user.preferences instanceof Map:', ionApi.user.preferences instanceof Map);
+console.log('  - user.preferences.get("theme"):', ionApi.user.preferences.get('theme'));
+console.log('  - user.roles instanceof Set:', ionApi.user.roles instanceof Set);
+console.log('  - user.roles.has("admin"):', ionApi.user.roles.has('admin'));
+console.log('  - user has "optionalField":', 'optionalField' in ionApi.user);
+
+// Summary
+console.log('\n' + '='.repeat(100));
+console.log('Summary');
+console.log('='.repeat(100));
+console.log('\nJSON Issues:');
+console.log('  ✗ Dates become strings (need manual conversion)');
+console.log('  ✗ NaN becomes null (information loss)');
+console.log('  ✗ Infinity becomes null (information loss)');
+console.log('  ✗ Maps become empty objects (data loss)');
+console.log('  ✗ Sets become empty objects (data loss)');
+console.log('  ✓ undefined properties are removed');
+
+console.log('\nION Guarantees:');
+console.log('  ✓ Dates preserved as Date objects');
+console.log('  ✓ NaN preserved as NaN');
+console.log('  ✓ Infinity preserved as Infinity');
+console.log('  ✓ Maps preserved with all entries and types');
+console.log('  ✓ Sets preserved with all values');
+console.log('  ✓ undefined properties are removed');
+console.log('  ✓ Throws errors for unsupported types (WeakMap, functions, etc.)');
+
+console.log('\n' + '='.repeat(100) + '\n');

package/benchmark.ts

@@ -0,0 +1,183 @@
+import ION from './index.ts';
+
+interface BenchmarkResult {
+  name: string;
+  jsonStringify: number;
+  ionStringify: number;
+  jsonParse: number;
+  ionParse: number;
+  jsonSize: number;
+  ionSize: number;
+}
+
+function benchmark(name: string, data: unknown, iterations = 10000): BenchmarkResult {
+  // Warmup
+  for (let i = 0; i < 100; i++) {
+    JSON.stringify(data);
+    ION.stringify(data);
+  }
+
+  // Benchmark JSON.stringify
+  const jsonStringifyStart = performance.now();
+  let jsonStr = '';
+  for (let i = 0; i < iterations; i++) {
+    jsonStr = JSON.stringify(data);
+  }
+  const jsonStringifyTime = performance.now() - jsonStringifyStart;
+
+  // Benchmark ION.stringify
+  const ionStringifyStart = performance.now();
+  let ionStr = '';
+  for (let i = 0; i < iterations; i++) {
+    ionStr = ION.stringify(data);
+  }
+  const ionStringifyTime = performance.now() - ionStringifyStart;
+
+  // Benchmark JSON.parse
+  const jsonParseStart = performance.now();
+  for (let i = 0; i < iterations; i++) {
+    JSON.parse(jsonStr);
+  }
+  const jsonParseTime = performance.now() - jsonParseStart;
+
+  // Benchmark ION.parse
+  const ionParseStart = performance.now();
+  for (let i = 0; i < iterations; i++) {
+    ION.parse(ionStr);
+  }
+  const ionParseTime = performance.now() - ionParseStart;
+
+  return {
+    name,
+    jsonStringify: jsonStringifyTime,
+    ionStringify: ionStringifyTime,
+    jsonParse: jsonParseTime,
+    ionParse: ionParseTime,
+    jsonSize: jsonStr.length,
+    ionSize: ionStr.length,
+  };
+}
+
+function formatTime(ms: number): string {
+  if (ms < 1) {
+    return `${(ms * 1000).toFixed(2)}μs`;
+  }
+  return `${ms.toFixed(2)}ms`;
+}
+
+function formatRatio(ion: number, json: number): string {
+  const ratio = ion / json;
+  if (ratio < 1) {
+    return `${(1 / ratio).toFixed(2)}x faster`;
+  } else {
+    return `${ratio.toFixed(2)}x slower`;
+  }
+}
+
+function printResults(results: BenchmarkResult[]): void {
+  console.log('\n' + '='.repeat(100));
+  console.log('ION vs JSON Benchmark Results');
+  console.log('='.repeat(100));
+
+  for (const result of results) {
+    console.log(`\n${result.name}`);
+    console.log('-'.repeat(100));
+
+    console.log('\nStringify:');
+    console.log(`  JSON:  ${formatTime(result.jsonStringify)}`);
+    console.log(`  ION:   ${formatTime(result.ionStringify)} (${formatRatio(result.ionStringify, result.jsonStringify)})`);
+
+    console.log('\nParse:');
+    console.log(`  JSON:  ${formatTime(result.jsonParse)}`);
+    console.log(`  ION:   ${formatTime(result.ionParse)} (${formatRatio(result.ionParse, result.jsonParse)})`);
+
+    console.log('\nSize:');
+    console.log(`  JSON:  ${result.jsonSize} bytes`);
+    console.log(`  ION:   ${result.ionSize} bytes (${result.ionSize > result.jsonSize ? '+' : ''}${result.ionSize - result.jsonSize} bytes)`);
+  }
+
+  console.log('\n' + '='.repeat(100));
+  console.log('Summary');
+  console.log('='.repeat(100));
+
+  const avgJsonStringify = results.reduce((sum, r) => sum + r.jsonStringify, 0) / results.length;
+  const avgIonStringify = results.reduce((sum, r) => sum + r.ionStringify, 0) / results.length;
+  const avgJsonParse = results.reduce((sum, r) => sum + r.jsonParse, 0) / results.length;
+  const avgIonParse = results.reduce((sum, r) => sum + r.ionParse, 0) / results.length;
+
+  console.log(`\nAverage Stringify: JSON ${formatTime(avgJsonStringify)}, ION ${formatTime(avgIonStringify)}`);
+  console.log(`Average Parse:     JSON ${formatTime(avgJsonParse)}, ION ${formatTime(avgIonParse)}`);
+  console.log(`\nION is ${formatRatio(avgIonStringify, avgJsonStringify)} for stringify`);
+  console.log(`ION is ${formatRatio(avgIonParse, avgJsonParse)} for parse`);
+  console.log('='.repeat(100) + '\n');
+}
+
+// Test data
+const smallObject = {
+  name: 'Alice',
+  age: 30,
+  active: true,
+};
+
+const mediumObject = {
+  users: [
+    { id: 1, name: 'Alice', email: 'alice@example.com', active: true },
+    { id: 2, name: 'Bob', email: 'bob@example.com', active: false },
+    { id: 3, name: 'Charlie', email: 'charlie@example.com', active: true },
+  ],
+  metadata: {
+    version: '1.0.0',
+    created: '2026-01-27',
+    count: 3,
+  },
+};
+
+const largeArray = Array.from({ length: 100 }, (_, i) => ({
+  id: i,
+  name: `User ${i}`,
+  email: `user${i}@example.com`,
+  score: Math.random() * 100,
+  active: i % 2 === 0,
+}));
+
+const deepNesting = {
+  level1: {
+    level2: {
+      level3: {
+        level4: {
+          level5: {
+            data: 'deep value',
+            numbers: [1, 2, 3, 4, 5],
+          },
+        },
+      },
+    },
+  },
+};
+
+const stringHeavy = {
+  description: 'This is a longer description with multiple sentences. '.repeat(10),
+  comments: Array.from({ length: 20 }, (_, i) => `Comment number ${i} with some text content`),
+};
+
+// Run benchmarks
+console.log('Running benchmarks...\n');
+
+const results: BenchmarkResult[] = [];
+
+console.log('[1/5] Small object...');
+results.push(benchmark('Small Object (3 properties)', smallObject, 50000));
+
+console.log('[2/5] Medium object...');
+results.push(benchmark('Medium Object (users array + metadata)', mediumObject, 20000));
+
+console.log('[3/5] Large array...');
+results.push(benchmark('Large Array (100 objects)', largeArray, 5000));
+
+console.log('[4/5] Deep nesting...');
+results.push(benchmark('Deep Nesting (5 levels)', deepNesting, 50000));
+
+console.log('[5/5] String heavy...');
+results.push(benchmark('String Heavy (long strings + array)', stringHeavy, 10000));
+
+printResults(results);