or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

comparison-classes.mdcomparison-functions.mdconfiguration.mdformatting.mdindex.md
tile.json

tessl/npm-tcompare

A comprehensive comparison library, for use in test frameworks

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/tcompare@9.0.x

To install, run

npx @tessl/cli install tessl/npm-tcompare@9.0.0

index.mddocs/

tcompare

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.

Package Information

  • Package Name: tcompare
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install tcompare

Core Imports

import { 
  same, 
  strict, 
  has, 
  hasStrict, 
  match, 
  matchOnly, 
  matchStrict, 
  matchOnlyStrict, 
  format,
  styles
} from "tcompare";
import type { 
  Result, 
  CompareOptions, 
  FormatOptions,
  SameOptions,
  Style, 
  StyleType,
  ReactElementToJSXStringOptions
} from "tcompare";

For CommonJS:

const { 
  same, 
  strict, 
  has, 
  hasStrict, 
  match, 
  matchOnly, 
  matchStrict, 
  matchOnlyStrict, 
  format,
  styles
} = require("tcompare");

Basic Usage

import { match, same, strict } from "tcompare";
import type { Result } from "tcompare";

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

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

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

Architecture

tcompare is built around several key components:

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

Capabilities

Comparison Functions

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.

interface Result {
  /** whether or not the objects are a satisfying match */
  match: boolean;
  /** Diff of formatted test object and expected pattern */
  diff: string;
}

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

function same(obj: any, pattern: any, options?: CompareOptions): Result;
function strict(obj: any, pattern: any, options?: CompareOptions): Result;
function has(obj: any, pattern: any, options?: CompareOptions): Result;
function hasStrict(obj: any, pattern: any, options?: CompareOptions): Result;
function match(obj: any, pattern: any, options?: CompareOptions): Result;
function matchOnly(obj: any, pattern: any, options?: CompareOptions): Result;
function matchStrict(obj: any, pattern: any, options?: CompareOptions): Result;
function matchOnlyStrict(obj: any, pattern: any, options?: CompareOptions): Result;

Comparison Functions

Comparison Classes

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.

class Same extends Format {
  constructor(obj: any, options: SameOptions);
  match: boolean;
  print(): string;
}

class Format {
  constructor(obj: any, options?: FormatOptions);
  print(): string;
}

Comparison Classes

Object Formatting

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

function format(obj: any, options?: FormatOptions): string;

interface FormatOptions {
  sort?: boolean;
  style?: StyleType;
  bufferChunkSize?: number;
  includeEnumerable?: boolean;
  includeGetters?: boolean;
  reactString?: boolean;
}

type StyleType = 'pretty' | 'js' | 'tight';

Formatting

Configuration Options

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

interface SameOptions extends FormatOptions {
  expect: any;
  parent?: Same;
  key?: any;
  expectKey?: any;
  diffContext?: number;
}

interface Style {
  fn: (fn: Function, cls: string) => string;
  setEmpty: (cls: string) => string;
  // ... extensive style configuration options
}

const styles: { [style in StyleType]: Style };

Configuration