0
# tcompare
1

2
tcompare is a comprehensive comparison library designed for use in test frameworks. It provides multiple comparison strategies ranging from loose pattern matching to strict deep equality, with detailed diff output and advanced formatting options. The library supports circular reference handling, React JSX element comparison, and customizable formatting styles.
3

4
## Package Information
5

6
- **Package Name**: tcompare
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install tcompare`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  same, 
16
  strict, 
17
  has, 
18
  hasStrict, 
19
  match, 
20
  matchOnly, 
21
  matchStrict, 
22
  matchOnlyStrict, 
23
  format,
24
  styles
25
} from "tcompare";
26
import type { 
27
  Result, 
28
  CompareOptions, 
29
  FormatOptions,
30
  SameOptions,
31
  Style, 
32
  StyleType,
33
  ReactElementToJSXStringOptions
34
} from "tcompare";
35
```
36

37
For CommonJS:
38

39
```javascript
40
const { 
41
  same, 
42
  strict, 
43
  has, 
44
  hasStrict, 
45
  match, 
46
  matchOnly, 
47
  matchStrict, 
48
  matchOnlyStrict, 
49
  format,
50
  styles
51
} = require("tcompare");
52
```
53

54
## Basic Usage
55

56
```typescript
57
import { match, same, strict } from "tcompare";
58
import type { Result } from "tcompare";
59

60
// Basic comparison with detailed diff output
61
const result: Result = match({ name: "Alice", age: 25 }, { name: "Alice" });
62
if (!result.match) {
63
  console.log("Objects don't match");
64
  console.log(result.diff);
65
} else {
66
  console.log("Match found!");
67
}
68

69
// Strict equality comparison
70
const strictResult = strict([1, 2, 3], [1, 2, 3]);
71
console.log(strictResult.match); // true
72

73
// Subset matching (has)
74
const hasResult = same({ a: 1, b: 2, c: 3 }, { a: 1, b: 2 });
75
console.log(hasResult.match); // true - object has required fields
76
```
77

78
## Architecture
79

80
tcompare is built around several key components:
81

82
- **Comparison Functions**: Eight convenience functions for different matching strategies
83
- **Comparison Classes**: Low-level classes for custom comparison logic and performance optimization
84
- **Formatting System**: Configurable object-to-string conversion with multiple styles
85
- **Diff Generation**: Patch-style diff output with circular reference support
86
- **Type System**: Full TypeScript support with comprehensive type definitions
87

88
## Capabilities
89

90
### Comparison Functions
91

92
Eight different comparison strategies from loose pattern matching to strict deep equality. Each returns a `Result` object with both boolean match status and detailed diff string.
93

94
```typescript { .api }
95
interface Result {
96
  /** whether or not the objects are a satisfying match */
97
  match: boolean;
98
  /** Diff of formatted test object and expected pattern */
99
  diff: string;
100
}
101

102
type CompareOptions = FormatOptions & Pick<SameOptions, 'diffContext'>;
103

104
function same(obj: any, pattern: any, options?: CompareOptions): Result;
105
function strict(obj: any, pattern: any, options?: CompareOptions): Result;
106
function has(obj: any, pattern: any, options?: CompareOptions): Result;
107
function hasStrict(obj: any, pattern: any, options?: CompareOptions): Result;
108
function match(obj: any, pattern: any, options?: CompareOptions): Result;
109
function matchOnly(obj: any, pattern: any, options?: CompareOptions): Result;
110
function matchStrict(obj: any, pattern: any, options?: CompareOptions): Result;
111
function matchOnlyStrict(obj: any, pattern: any, options?: CompareOptions): Result;
112
```
113

114
[Comparison Functions](./comparison-functions.md)
115

116
### Comparison Classes
117

118
Direct access to comparison classes for advanced usage and performance optimization. All classes extend the base Format class and provide `print()` method for diff generation.
119

120
```typescript { .api }
121
class Same extends Format {
122
  constructor(obj: any, options: SameOptions);
123
  match: boolean;
124
  print(): string;
125
}
126

127
class Format {
128
  constructor(obj: any, options?: FormatOptions);
129
  print(): string;
130
}
131
```
132

133
[Comparison Classes](./comparison-classes.md)
134

135
### Object Formatting
136

137
Standalone formatting functionality for converting any JavaScript value to a readable string representation with multiple style options.
138

139
```typescript { .api }
140
function format(obj: any, options?: FormatOptions): string;
141

142
interface FormatOptions {
143
  sort?: boolean;
144
  style?: StyleType;
145
  bufferChunkSize?: number;
146
  includeEnumerable?: boolean;
147
  includeGetters?: boolean;
148
  reactString?: boolean;
149
}
150

151
type StyleType = 'pretty' | 'js' | 'tight';
152
```
153

154
[Formatting](./formatting.md)
155

156
### Configuration Options
157

158
Comprehensive configuration system for customizing comparison behavior, diff output, and object formatting across all functions and classes.
159

160
```typescript { .api }
161
interface SameOptions extends FormatOptions {
162
  expect: any;
163
  parent?: Same;
164
  key?: any;
165
  expectKey?: any;
166
  diffContext?: number;
167
}
168

169
interface Style {
170
  fn: (fn: Function, cls: string) => string;
171
  setEmpty: (cls: string) => string;
172
  // ... extensive style configuration options
173
}
174

175
const styles: { [style in StyleType]: Style };
176
```
177

178
[Configuration](./configuration.md)