0
# Comparison Functions
1

2
tcompare provides eight different comparison functions, each implementing a specific matching strategy. All functions return a `Result` object containing both the boolean match result and a detailed diff string.
3

4
## Capabilities
5

6
### Result Interface
7

8
All comparison functions return the same Result interface.
9

10
```typescript { .api }
11
interface Result {
12
  /** whether or not the objects are a satisfying match */
13
  match: boolean;
14
  /** Diff of formatted test object and expected pattern. Only shows properties which differ, not the entire object. */
15
  diff: string;
16
}
17

18
type CompareOptions = FormatOptions & Pick<SameOptions, 'diffContext'>;
19
```
20

21
### same Function
22

23
Deep equivalence comparison with loose matching. Ensures all items in the pattern are found in the object and vice versa, using type coercion (e.g., `1` matches `'1'`).
24

25
```typescript { .api }
26
/**
27
 * Deep equivalence comparison with loose matching
28
 * @param obj - The object to test
29
 * @param pattern - The expected pattern
30
 * @param options - Comparison and formatting options
31
 * @returns Result with match status and diff
32
 */
33
function same(obj: any, pattern: any, options?: CompareOptions): Result;
34
```
35

36
**Usage Examples:**
37

38
```typescript
39
import { same } from "tcompare";
40

41
// Loose equality - passes with type coercion
42
const result1 = same([1, 2, 3], ["1", "2", "3"]);
43
console.log(result1.match); // true
44

45
// Object comparison
46
const result2 = same(
47
  { name: "Alice", age: 25 },
48
  { name: "Alice", age: "25" }
49
);
50
console.log(result2.match); // true - age coerced from string to number
51
```
52

53
### strict Function
54

55
Deep equality comparison without type coercion. All items must match strictly, objects must have the same constructors, and no type coercion is performed.
56

57
```typescript { .api }
58
/**
59
 * Deep equality comparison without type coercion
60
 * @param obj - The object to test
61
 * @param pattern - The expected pattern
62
 * @param options - Comparison and formatting options
63
 * @returns Result with match status and diff
64
 */
65
function strict(obj: any, pattern: any, options?: CompareOptions): Result;
66
```
67

68
**Usage Examples:**
69

70
```typescript
71
import { strict } from "tcompare";
72

73
// Strict equality - fails without type coercion
74
const result1 = strict([1, 2, 3], ["1", "2", "3"]);
75
console.log(result1.match); // false
76

77
// Must match exactly including constructors
78
const result2 = strict(new Date("2023-01-01"), new Date("2023-01-01"));
79
console.log(result2.match); // true
80
```
81

82
### has Function
83

84
Subset matching with loose comparison. Ensures all items in the pattern are found in the object, but ignores additional items in the object. Uses loose matching like `same`.
85

86
```typescript { .api }
87
/**
88
 * Subset matching with loose comparison
89
 * @param obj - The object to test
90
 * @param pattern - The pattern that must be present in the object
91
 * @param options - Comparison and formatting options
92
 * @returns Result with match status and diff
93
 */
94
function has(obj: any, pattern: any, options?: CompareOptions): Result;
95
```
96

97
**Usage Examples:**
98

99
```typescript
100
import { has } from "tcompare";
101

102
// Object with extra properties still matches
103
const result1 = has(
104
  { name: "Alice", age: 25, city: "NYC" },
105
  { name: "Alice", age: "25" }
106
);
107
console.log(result1.match); // true - extra 'city' field ignored
108

109
// Array subset matching
110
const result2 = has([1, 2, 3, 4], [1, 2]);
111
console.log(result2.match); // true - extra elements ignored
112
```
113

114
### hasStrict Function
115

116
Subset matching with strict comparison for primitive values. Like `has` but uses strict equality for primitives while allowing constructor differences for objects.
117

118
```typescript { .api }
119
/**
120
 * Subset matching with strict comparison
121
 * @param obj - The object to test
122
 * @param pattern - The pattern that must be present in the object
123
 * @param options - Comparison and formatting options
124
 * @returns Result with match status and diff
125
 */
126
function hasStrict(obj: any, pattern: any, options?: CompareOptions): Result;
127
```
128

129
**Usage Examples:**
130

131
```typescript
132
import { hasStrict } from "tcompare";
133

134
// Strict matching for primitives
135
const result1 = hasStrict(
136
  { name: "Alice", age: 25 },
137
  { name: "Alice", age: "25" }
138
);
139
console.log(result1.match); // false - age string vs number
140

141
// Object matching allows constructor differences
142
const result2 = hasStrict(
143
  new URL("https://example.com/path"),
144
  { pathname: "/path" }
145
);
146
console.log(result2.match); // true
147
```
148

149
### match Function
150

151
The most flexible matching strategy. Supports multiple pattern types including regular expressions, constructors, and string matching. Ideal for loose validation scenarios.
152

153
```typescript { .api }
154
/**
155
 * Flexible pattern matching with support for regex, constructors, and string patterns
156
 * @param obj - The object to test
157
 * @param pattern - The pattern to match (can be regex, constructor, string, etc.)
158
 * @param options - Comparison and formatting options
159
 * @returns Result with match status and diff
160
 */
161
function match(obj: any, pattern: any, options?: CompareOptions): Result;
162
```
163

164
**Usage Examples:**
165

166
```typescript
167
import { match } from "tcompare";
168

169
// Regular expression matching
170
const result1 = match("hello world", /^hello/);
171
console.log(result1.match); // true
172

173
// Constructor matching
174
const result2 = match(42, Number);
175
console.log(result2.match); // true
176

177
// String substring matching
178
const result3 = match("hello world", "world");
179
console.log(result3.match); // true
180

181
// Date string parsing
182
const result4 = match(new Date("2023-01-01"), "2023-01-01");
183
console.log(result4.match); // true
184

185
// Complex object with pattern matching
186
const result5 = match(
187
  { name: "Alice", age: 25, email: "alice@example.com" },
188
  { name: String, age: Number, email: /@example\.com$/ }
189
);
190
console.log(result5.match); // true
191
```
192

193
### matchOnly Function
194

195
Uses the flexible matching from `match` but requires that only the specified fields in the pattern are present in the object. Extra fields cause failure unless they're null or undefined.
196

197
```typescript { .api }
198
/**
199
 * Pattern matching with strict object shape requirements
200
 * @param obj - The object to test
201
 * @param pattern - The exact pattern the object must match
202
 * @param options - Comparison and formatting options
203
 * @returns Result with match status and diff
204
 */
205
function matchOnly(obj: any, pattern: any, options?: CompareOptions): Result;
206
```
207

208
**Usage Examples:**
209

210
```typescript
211
import { matchOnly } from "tcompare";
212

213
// Fails due to extra field
214
const result1 = matchOnly(
215
  { name: "Alice", age: 25, city: "NYC" },
216
  { name: String, age: Number }
217
);
218
console.log(result1.match); // false - 'city' field not allowed
219

220
// Passes with exact shape
221
const result2 = matchOnly(
222
  { name: "Alice", age: 25 },
223
  { name: String, age: Number }
224
);
225
console.log(result2.match); // true
226
```
227

228
### matchStrict Function
229

230
Like `match` but fails when two values are loosely equal but not strictly equal (`a == b && !(a === b)`).
231

232
```typescript { .api }
233
/**
234
 * Flexible pattern matching without type coercion
235
 * @param obj - The object to test
236
 * @param pattern - The pattern to match
237
 * @param options - Comparison and formatting options
238
 * @returns Result with match status and diff
239
 */
240
function matchStrict(obj: any, pattern: any, options?: CompareOptions): Result;
241
```
242

243
**Usage Examples:**
244

245
```typescript
246
import { matchStrict } from "tcompare";
247

248
// Regular expression still works
249
const result1 = matchStrict("hello world", /^hello/);
250
console.log(result1.match); // true
251

252
// But strict equality is enforced for simple comparisons
253
const result2 = matchStrict(1, "1");
254
console.log(result2.match); // false - no type coercion
255
```
256

257
### matchOnlyStrict Function
258

259
Combines the strict shape requirements of `matchOnly` with the strict equality requirements of `matchStrict`.
260

261
```typescript { .api }
262
/**
263
 * Strict pattern matching with strict object shape requirements
264
 * @param obj - The object to test
265
 * @param pattern - The exact pattern the object must match strictly
266
 * @param options - Comparison and formatting options
267
 * @returns Result with match status and diff
268
 */
269
function matchOnlyStrict(obj: any, pattern: any, options?: CompareOptions): Result;
270
```
271

272
**Usage Examples:**
273

274
```typescript
275
import { matchOnlyStrict } from "tcompare";
276

277
// Most restrictive comparison - exact shape and strict values
278
const result = matchOnlyStrict(
279
  { name: "Alice", age: 25 },
280
  { name: "Alice", age: 25 }
281
);
282
console.log(result.match); // true
283

284
// Fails on both extra fields and type coercion
285
const result2 = matchOnlyStrict(
286
  { name: "Alice", age: "25", city: "NYC" },
287
  { name: "Alice", age: 25 }
288
);
289
console.log(result2.match); // false
290
```
291

292
## Comparison Strategy Guide
293

294
Choose the right comparison function based on your needs:
295

296
- **`same`**: Full deep equality with type coercion (most permissive)
297
- **`strict`**: Full deep equality without type coercion
298
- **`has`**: Subset matching with type coercion (good for partial validation)
299
- **`hasStrict`**: Subset matching without type coercion
300
- **`match`**: Pattern-based matching (regex, constructors, strings)
301
- **`matchOnly`**: Pattern matching with exact object shape
302
- **`matchStrict`**: Pattern matching without type coercion
303
- **`matchOnlyStrict`**: Most restrictive - exact shape and strict patterns