Should.js Type Adaptors

Warnings

• gotcha This package (`should-type-adaptors`) is a low-level utility for `should.js` and is not typically used for direct assertions. Its functions are primarily intended to extend or modify how `should.js` processes different data types during its own assertion logic.
  Fix: Focus on integrating `should-type-adaptors` with `should.js` via `should.use()` or by directly calling its utility functions to augment existing assertion behavior, rather than using its exports as standalone assertion methods.
• gotcha The package's `package.json` does not specify `"type": "module"`, indicating it is primarily a CommonJS module. While modern bundlers can often handle ESM imports, direct usage in Node.js without specific configuration might require `require()`.
  Fix: For compatibility across all Node.js environments, use `const { addTypeAdaptor } = require('should-type-adaptors');` or ensure your project's build setup correctly transpiles or handles CommonJS modules when using ESM `import`.
• deprecated The `should-type-adaptors` package has seen infrequent updates, with its last commit related to dependency updates in late 2019. While it remains functional within the `should.js` ecosystem, active development on this specific utility has significantly slowed.
  Fix: Evaluate if the functionality is still required or if `should.js` itself (or other `should.js` plugins) has incorporated similar capabilities. Be prepared for minimal future feature development or breaking changes in upstream `should.js` that might not be immediately reflected here.

Install

• npm install should-type-adaptors npm
• yarn add should-type-adaptors yarn
• pnpm add should-type-adaptors pnpm

Imports

• addTypeAdaptor
  wrong:

  const { addTypeAdaptor } = require('should-type-adaptors');

  correct:

  import { addTypeAdaptor } from 'should-type-adaptors';

  Primarily designed for CommonJS (`require`), but bundlers can often handle ESM import. Explicit `require` is safer for older Node.js environments.
• convert
  wrong:

  const { convert } = require('should-type-adaptors');

  correct:

  import { convert } from 'should-type-adaptors';

  Used for converting values using registered adaptors. Less common for direct user invocation than `addTypeAdaptor`.
• isAdapted
  wrong:

  const { isAdapted } = require('should-type-adaptors');

  correct:

  import { isAdapted } from 'should-type-adaptors';

  Checks if a specific type has an adaptor registered. Like `convert`, it's a utility for deeper integration, not typical end-user assertion.

Quickstart

This quickstart demonstrates how to register a custom type adaptor for a user-defined class (`MyCustomType`) with `should-type-adaptors`. It configures `should.js` to use a custom `valueOf` method for deep comparisons, enabling robust assertions on complex objects. This is typically how `should-type-adaptors` extends `should.js`'s capabilities.

import should from 'should';
import { addTypeAdaptor } from 'should-type-adaptors';

// Define a custom class
class MyCustomType {
  constructor(id, value) {
    this.customId = id;
    this.data = value;
  }

  // A method that might be important for comparison
  getFormattedData() {
    return `ID: ${this.customId}, Data: ${this.data}`;
  }
}

// Register a type adaptor for MyCustomType to define how 'should.js' should compare it
// This adaptor tells should.js to use 'getFormattedData' for deep comparisons.
addTypeAdaptor(MyCustomType, {
  valueOf: (instance) => instance.getFormattedData(),
  // You can also define custom 'eql' or 'inspect' methods here
  // eql: (a, b) => a.customId === b.customId && a.data === b.data,
  // inspect: (instance, level) => `MyCustomType { id: ${instance.customId}, data: '${instance.data}' }`
});

const instance1 = new MyCustomType(1, 'hello');
const instance2 = new MyCustomType(1, 'hello');
const instance3 = new MyCustomType(2, 'world');

// Now should.js can compare custom types based on their adapted value
should(instance1).eql(instance2); // This assertion will pass because valueOf makes them deeply equal
should(instance1).not.eql(instance3); // This assertion will pass

console.log('Assertions passed successfully!');

// Example of direct usage of convert (less common)
// import { convert } from 'should-type-adaptors';
// const convertedValue = convert(instance1); // Will be 'ID: 1, Data: hello'
// console.log(convertedValue);