0
# Configuration
1

2
tcompare provides extensive configuration options for customizing comparison behavior, diff output, and object formatting. All options are type-safe and well-documented for easy customization.
3

4
## Capabilities
5

6
### CompareOptions Type
7

8
Options available to all comparison functions, combining formatting and comparison-specific settings.
9

10
```typescript { .api }
11
/**
12
 * Options that can be used to set how diffs are formatted
13
 */
14
type CompareOptions = FormatOptions & Pick<SameOptions, 'diffContext'>;
15
```
16

17
### FormatOptions Interface
18

19
Core formatting options available to all formatting and comparison operations.
20

21
```typescript { .api }
22
/**
23
 * Options to control the formatting of objects
24
 */
25
interface FormatOptions {
26
  /** Sort object keys alphabetically for deterministic output */
27
  sort?: boolean;
28
  /** Formatting style - controls output format and syntax */
29
  style?: StyleType;
30
  /** Number of bytes to show per line when printing long Buffers (default: 32) */
31
  bufferChunkSize?: number;
32
  /** Include enumerable properties from prototype chain */
33
  includeEnumerable?: boolean;
34
  /** Include getter properties (warning: may trigger side effects) */
35
  includeGetters?: boolean;
36
  /** Represent and compare React elements as JSX strings (pretty style only, default: true) */
37
  reactString?: boolean;
38
}
39

40
type StyleType = 'pretty' | 'js' | 'tight';
41
```
42

43
**Usage Examples:**
44

45
```typescript
46
import { same, format } from "tcompare";
47

48
// Basic formatting options
49
const options = {
50
  sort: true,           // Alphabetical key sorting
51
  style: "js" as const, // JavaScript syntax
52
  bufferChunkSize: 16   // Smaller buffer chunks
53
};
54

55
const result = same(obj1, obj2, options);
56
const formatted = format(obj1, options);
57
```
58

59
### SameOptions Interface
60

61
Extended options for all comparison classes, including the expected pattern and diff configuration.
62

63
```typescript { .api }
64
/**
65
 * Options for all comparison operations
66
 */
67
interface SameOptions extends FormatOptions {
68
  /** The pattern to test against (required for comparison classes) */
69
  expect: any;
70
  /** Parent comparison object for nested comparisons */
71
  parent?: Same;
72
  /** Key in parent object being compared */
73
  key?: any;
74
  /** Corresponding key in expected pattern */
75
  expectKey?: any;
76
  /** Number of lines of context to show around changes in diffs (default: 10) */
77
  diffContext?: number;
78
}
79
```
80

81
**Usage Examples:**
82

83
```typescript
84
import { Same } from "tcompare";
85

86
// Comprehensive comparison options
87
const options = {
88
  expect: { name: "Alice", age: 25 },
89
  style: "pretty" as const,
90
  sort: true,
91
  diffContext: 5,        // Show 5 lines of context around changes
92
  reactString: false     // Disable JSX formatting
93
};
94

95
const comparison = new Same(testObject, options);
96
const diff = comparison.print();
97
```
98

99
### React Element Options
100

101
Options for configuring React element formatting when `reactString` is enabled.
102

103
```typescript { .api }
104
/**
105
 * Options for React element to JSX string conversion
106
 * Re-exported from react-element-to-jsx-string package
107
 */
108
interface ReactElementToJSXStringOptions {
109
  /** Show default props in JSX output */
110
  showDefaultProps?: boolean;
111
  /** Show functions as anonymous functions */
112
  showFunctions?: boolean;
113
  /** Function to filter out props from JSX output */
114
  filterProps?: string[];
115
  /** Maximum depth for nested elements */
116
  maxInlineAttributesLineLength?: number;
117
  /** Sort props alphabetically */
118
  sortProps?: boolean;
119
  /** Use single quotes for props */
120
  useBooleanShorthandSyntax?: boolean;
121
  /** Tab size for indentation */
122
  tabStop?: number;
123
}
124
```
125

126
**Usage Examples:**
127

128
```typescript
129
import { format } from "tcompare";
130
import type { ReactElementToJSXStringOptions } from "tcompare";
131

132
// React element formatting with custom options
133
const reactOptions: ReactElementToJSXStringOptions = {
134
  showDefaultProps: false,
135
  sortProps: true,
136
  useBooleanShorthandSyntax: true
137
};
138

139
const formatOptions = {
140
  style: "pretty" as const,
141
  reactString: true,
142
  // Note: ReactElementToJSXStringOptions are used internally
143
  // when reactString is true
144
};
145

146
const element = <MyComponent name="test" active={true} />;
147
const formatted = format(element, formatOptions);
148
```
149

150
### Style Configuration
151

152
Three predefined styles with different output characteristics and use cases.
153

154
```typescript { .api }
155
type StyleType = 'pretty' | 'js' | 'tight';
156

157
/**
158
 * Style configuration object defining how values are formatted
159
 */
160
interface Style {
161
  /** Format functions with optional class names */
162
  fn: (fn: Function | ((...a: any[]) => any), cls: string) => string;
163
  /** Format empty Set objects */
164
  setEmpty: (cls: string) => string;
165
  /** Format Set opening */
166
  setHead: (cls: string) => string;
167
  /** Format Set closing */
168
  setTail: (indent: string) => string;
169
  /** Separator between Set entries */
170
  setEntrySep: () => string;
171
  /** Format empty Map objects */
172
  mapEmpty: (cls: string) => string;
173
  /** Format Map opening */
174
  mapHead: (cls: string) => string;
175
  /** Format Map closing */
176
  mapTail: (indent: string) => string;
177
  /** Format Map key start */
178
  mapKeyStart: () => string;
179
  /** Separator between Map key and value */
180
  mapKeyValSep: () => string;
181
  /** Separator between Map entries */
182
  mapEntrySep: () => string;
183
  /** Format circular references */
184
  circular: (node: Format) => string;
185
  /** Format reference IDs */
186
  nodeId: (id: number) => string;
187
  /** Additional formatting methods for errors, objects, arrays, etc. */
188
  // ... extensive additional methods
189
}
190

191
/**
192
 * Predefined styles for different formatting needs
193
 */
194
const styles: { [style in StyleType]: Style };
195
```
196

197
**Style Comparison Examples:**
198

199
```typescript
200
import { format, styles } from "tcompare";
201

202
const data = {
203
  map: new Map([["key1", "value1"], ["key2", "value2"]]),
204
  set: new Set(["a", "b", "c"]),
205
  array: [1, 2, 3]
206
};
207

208
// Pretty style - human readable with type indicators
209
console.log(format(data, { style: "pretty" }));
210
/*
211
Object {
212
  "map": Map {
213
    "key1" => "value1",
214
    "key2" => "value2",
215
  },
216
  "set": Set {
217
    "a",
218
    "b",
219
    "c",
220
  },
221
  "array": Array [
222
    1,
223
    2,
224
    3,
225
  ],
226
}
227
*/
228

229
// JavaScript style - valid JS syntax
230
console.log(format(data, { style: "js" }));
231
/*
232
{
233
  "map": new Map([
234
    ["key1", "value1"],
235
    ["key2", "value2"],
236
  ]),
237
  "set": new Set([
238
    "a",
239
    "b", 
240
    "c",
241
  ]),
242
  "array": [
243
    1,
244
    2,
245
    3,
246
  ],
247
}
248
*/
249

250
// Tight style - minimal whitespace
251
console.log(format(data, { style: "tight" }));
252
// {"map":new Map([["key1","value1"],["key2","value2"],]),"set":new Set(["a","b","c",]),"array":[1,2,3,],}
253
```
254

255
### Diff Context Configuration
256

257
Control how much context is shown around changes in diff output.
258

259
```typescript { .api }
260
interface SameOptions {
261
  /** 
262
   * Number of lines of context to show around changes in diffs
263
   * Higher values show more surrounding unchanged content
264
   * Lower values focus on just the changes
265
   * Default: 10
266
   */
267
  diffContext?: number;
268
}
269
```
270

271
**Usage Examples:**
272

273
```typescript
274
import { same } from "tcompare";
275

276
const obj1 = {
277
  a: 1, b: 2, c: 3, d: 4, e: 5,
278
  f: 6, g: 7, h: 8, i: 9, j: 10,
279
  k: 11, l: 12, m: 13, n: 14, o: 15
280
};
281

282
const obj2 = {
283
  ...obj1,
284
  h: 999  // Changed value
285
};
286

287
// Minimal context - focus on changes
288
const minimalResult = same(obj1, obj2, { diffContext: 1 });
289
console.log(minimalResult.diff);
290
/*
291
--- expected
292
+++ actual
293
@@ -6,3 +6,3 @@
294
   "g": 7,
295
-  "h": 8,
296
+  "h": 999,
297
   "i": 9,
298
*/
299

300
// More context - show surrounding unchanged content
301
const contextResult = same(obj1, obj2, { diffContext: 5 });
302
console.log(contextResult.diff);
303
/*
304
--- expected  
305
+++ actual
306
@@ -4,7 +4,7 @@
307
   "e": 5,
308
   "f": 6,
309
   "g": 7,
310
-  "h": 8,
311
+  "h": 999,
312
   "i": 9,
313
   "j": 10,
314
   "k": 11,
315
*/
316
```
317

318
### Buffer Configuration
319

320
Special configuration for Buffer object display.
321

322
```typescript { .api }
323
interface FormatOptions {
324
  /**
325
   * Number of bytes to show per line when printing long Buffer objects
326
   * Each line shows hex values and ASCII representation
327
   * Default: 32 bytes per line
328
   */
329
  bufferChunkSize?: number;
330
}
331
```
332

333
**Usage Examples:**
334

335
```typescript
336
import { format } from "tcompare";
337

338
const buffer = Buffer.from("Hello, World! This is a test buffer with more content.");
339

340
// Default chunk size (32 bytes per line)
341
console.log(format(buffer));
342
/*
343
Buffer <
344
  48 65 6c 6c 6f 2c 20 57 6f 72 6c 64 21 20 54 68 |Hello, World! Th|
345
  69 73 20 69 73 20 61 20 74 65 73 74 20 62 75 66 |is a test buf|
346
  66 65 72 20 77 69 74 68 20 6d 6f 72 65 20 63 6f |fer with more co|
347
  6e 74 65 6e 74 2e                               |ntent.|
348
>
349
*/
350

351
// Smaller chunks (16 bytes per line)
352
console.log(format(buffer, { bufferChunkSize: 16 }));
353
/*
354
Buffer <
355
  48 65 6c 6c 6f 2c 20 57 |Hello, W|
356
  6f 72 6c 64 21 20 54 68 |orld! Th|
357
  69 73 20 69 73 20 61 20 |is a |
358
  74 65 73 74 20 62 75 66 |test buf|
359
  // ... continues
360
>
361
*/
362

363
// Larger chunks (64 bytes per line)
364
console.log(format(buffer, { bufferChunkSize: 64 }));
365
/*
366
Buffer <
367
  48 65 6c 6c 6f 2c 20 57 6f 72 6c 64 21 20 54 68 69 73 20 69 73 20 61 20 74 65 73 74 20 62 |Hello, World! This is a test b|
368
  75 66 66 65 72 20 77 69 74 68 20 6d 6f 72 65 20 63 6f 6e 74 65 6e 74 2e                   |uffer with more content.|
369
>
370
*/
371
```
372

373
### React Element Configuration
374

375
Control how React elements are formatted and compared.
376

377
```typescript { .api }
378
interface FormatOptions {
379
  /**
380
   * Represent and compare React elements as JSX strings
381
   * Only supported in 'pretty' formatting style
382
   * When enabled, React elements are first compared as JSX strings
383
   * If JSX strings match, elements are considered equivalent
384
   * If JSX strings don't match, falls back to object comparison
385
   * Default: true
386
   */
387
  reactString?: boolean;
388
}
389
```
390

391
**Usage Examples:**
392

393
```typescript
394
import { format, same } from "tcompare";
395
import React from "react";
396

397
const element1 = <div className="container">Hello</div>;
398
const element2 = <div className="container">Hello</div>;
399

400
// With JSX string formatting (default)
401
console.log(format(element1));
402
// <div className="container">Hello</div>
403

404
const result1 = same(element1, element2, { reactString: true });
405
console.log(result1.match); // true - JSX strings match
406

407
// Without JSX string formatting - shows object structure
408
console.log(format(element1, { reactString: false }));
409
/*
410
Object {
411
  "type": "div",
412
  "props": Object {
413
    "className": "container", 
414
    "children": "Hello",
415
  },
416
}
417
*/
418
```
419

420
### Property Inclusion Configuration
421

422
Control which object properties are included in formatting and comparison.
423

424
```typescript { .api }
425
interface FormatOptions {
426
  /**
427
   * Include enumerable properties from prototype chain
428
   * By default, only own properties are included
429
   * Warning: May include unexpected inherited properties
430
   */
431
  includeEnumerable?: boolean;
432
  
433
  /**
434
   * Include getter properties when formatting/comparing
435
   * Warning: Calling getters may trigger side effects
436
   */
437
  includeGetters?: boolean;
438
}
439
```
440

441
**Usage Examples:**
442

443
```typescript
444
import { format } from "tcompare";
445

446
class Parent {
447
  parentProp = "parent";
448
  get parentGetter() { return "parent getter"; }
449
}
450

451
class Child extends Parent {
452
  childProp = "child";
453
  get childGetter() { return "child getter"; }
454
}
455

456
const instance = new Child();
457

458
// Default - only own properties
459
console.log(format(instance));
460
/*
461
Child {
462
  "childProp": "child",
463
}
464
*/
465

466
// Include enumerable properties from prototype
467
console.log(format(instance, { includeEnumerable: true }));
468
/*
469
Child {
470
  "childProp": "child",
471
  "parentProp": "parent",
472
}
473
*/
474

475
// Include getters (may trigger side effects)
476
console.log(format(instance, { includeGetters: true }));
477
/*
478
Child {
479
  "childProp": "child",
480
  "childGetter": "child getter",
481
}
482
*/
483

484
// Include both
485
console.log(format(instance, { 
486
  includeEnumerable: true, 
487
  includeGetters: true 
488
}));
489
/*
490
Child {
491
  "childProp": "child",
492
  "childGetter": "child getter",
493
  "parentProp": "parent",
494
  "parentGetter": "parent getter",
495
}
496
*/
497
```
498

499
### Key Sorting Configuration
500

501
Enable deterministic output by sorting object keys alphabetically.
502

503
```typescript { .api }
504
interface FormatOptions {
505
  /**
506
   * Sort object keys alphabetically
507
   * Ensures consistent output order regardless of key insertion order
508
   * Important for deterministic serialization and testing
509
   */
510
  sort?: boolean;
511
}
512
```
513

514
**Usage Examples:**
515

516
```typescript
517
import { format } from "tcompare";
518

519
const obj = { z: 1, a: 2, m: 3, b: 4 };
520

521
// Default - insertion order preserved
522
console.log(format(obj));
523
/*
524
Object {
525
  "z": 1,
526
  "a": 2,
527
  "m": 3,
528
  "b": 4,
529
}
530
*/
531

532
// Sorted - alphabetical order
533
console.log(format(obj, { sort: true }));
534
/*
535
Object {
536
  "a": 2,
537
  "b": 4,
538
  "m": 3,
539
  "z": 1,
540
}
541
*/
542
```
543

544
## Configuration Best Practices
545

546
### Performance Considerations
547

548
- Use `includeGetters: false` (default) to avoid side effects
549
- Consider `diffContext` size for large objects - smaller values improve readability
550
- `tight` style is fastest but least readable
551

552
### Testing and Debugging
553

554
- Use `sort: true` for deterministic test output
555
- Increase `diffContext` when debugging complex object differences
556
- Use `pretty` style for human-readable debugging output
557
- Use `js` style when you need to copy-paste test data
558

559
### Production Usage
560

561
- Disable `includeEnumerable` unless specifically needed
562
- Be cautious with `includeGetters` in production due to side effects
563
- Consider `bufferChunkSize` based on your typical buffer sizes
564
- Use appropriate `style` based on your output destination (logs, files, etc.)
565

566
## Predefined Styles
567

568
The `styles` constant provides access to the three predefined formatting styles.
569

570
```typescript { .api }
571
/**
572
 * Collection of predefined formatting styles
573
 */
574
const styles: { [style in StyleType]: Style };
575

576
/**
577
 * Individual style implementations
578
 */
579
interface Style {
580
  /** Format functions with optional class names */
581
  fn: (fn: Function, cls: string) => string;
582
  /** Format empty Set objects */
583
  setEmpty: (cls: string) => string;
584
  /** Format Set opening delimiter */
585
  setHead: (cls: string) => string;
586
  /** Format Set closing delimiter */
587
  setTail: (indent: string) => string;
588
  /** Format Map empty objects */
589
  mapEmpty: (cls: string) => string;
590
  /** Format Map opening delimiter */
591
  mapHead: (cls: string) => string;
592
  /** Format Map closing delimiter */
593
  mapTail: (indent: string) => string;
594
  /** Format circular reference markers */
595
  circular: (node: any) => string;
596
  /** Format node identifiers for circular references */
597
  nodeId: (id: number) => string;
598
  /** Additional formatting functions for Error objects, Buffers, Arrays, etc. */
599
  [key: string]: any;
600
}
601
```
602

603
**Usage Examples:**
604

605
```typescript
606
import { styles, format } from "tcompare";
607

608
// Access individual style configurations
609
const prettyStyle = styles.pretty;
610
const jsStyle = styles.js;
611
const tightStyle = styles.tight;
612

613
// Custom formatting using specific style
614
const obj = { name: "test", values: [1, 2, 3] };
615

616
// These are equivalent:
617
console.log(format(obj, { style: "pretty" }));
618
console.log(new Format(obj, { style: "pretty" }).print());
619

620
// Direct style access for custom implementations
621
const customFormatter = {
622
  ...styles.pretty,
623
  // Override specific formatting functions
624
  fn: (fn: Function, cls: string) => `[Function: ${fn.name}]`
625
};
626
```