escss-estest

What is ESCSS-ESTest?

A passive, non-intrusive JavaScript runtime validator designed to achieve 100% function coverage.

Features

• ✅ TypeScript autocompletion.
• 🧪 Supports E2E & unit testing.
• ⚙️ Works in Node.js & modern browsers.
• ❤️‍🔥 Built with security & developer experience at heart.
• 🎯 Non-intrusive & concise API to achieve 100% function coverage.
• 🔥 Runtime dependency error detection to eliminate dependency hell.
• 🪶 2.7 kB (minified + gzipped), zero dependencies, and no vendor lock-in.
• ⚡ (Optional) runtime testing with minimal performance impact.

benchmark

source: ESTest-benchmark-repo

Installation

  npm add escss-estest

  yarn add escss-estest

  pnpm add escss-estest

  bun add escss-estest

Core Concept

Water filter

• Inspired by TDD, it's a filter for your code, making sure only clean results come through.

function sum(a, b) {
  // unhappy path: {...}
  // Unhappy path filter. console.error (non-breaking). Collapsible. Removable.
  {
    ESTest(a, "number");
    ESTest(b, "number");
  }

  // Happy path: inputs are valid
  return a + b;
}

Core API

ESTest(input, type = "null", message = globalThis.__ESCSS_ESTEST__.message)

• Non-breaking error logging via console.error(...)

case 1

import { ESTest } from "escss-estest";

function sum(a, b) {
  {
    ESTest(a, "number");
    ESTest(b, "number");
  }

  return a + b;
}

case 2

import { ESTest } from "escss-estest";

async function getApi(a, b) {
  const apiData = await fetch("https://www.just-an-example.com/1");
  const data = await apiData.json();

  /**
   * data = {
   *    name: "mike lee",
   *    email: "[e-mail]"
   *    info: [
   *      {
   *        id: '1',
   *        city: 'foo',
   *        statusCode: 111
   *      },
   *      {
   *        id: '2',
   *        city: 'bar',
   *        statusCode: 222
   *      }
   *    ]
   * }
   */

  // Hint: Prevent undefined errors with optional chaining (?.)
  {
    ESTest(data.name, "string").regex(/^mike lee$/);
    ESTest(data.email, "string").email();
    ESTest(data.info[0]?.id, "string?");
    ESTest(data.info[0]?.city, "string?");
    ESTest(data.info[0]?.statusCode, "number?");
  }

  return data;
}

image

source: mike-demo-project

unSafeESTest(input, type = "null", message = globalThis.__ESCSS_ESTEST__.message)

• Breaking error throwing via throw new Error(...)

import { ESTest, unSafeESTest } from "escss-estest";
import express from "express";

const app = express();
const port = 3000;

app.use(express.json());

app.post("/demo", (req, res) => {
  try {
    const data = req.body;

    /**
     * data = {
     *    name: "mike lee",
     *    email: "[e-mail]"
     * }
     */

    {
      unSafeESTest(data.name, "string", "wrong name").regex(/^mike lee$/);
      unSafeESTest(data.email, "string", "invalid email").email();
    }

    res.json({ message: "ok" });
  } catch (err) {
    res.status(400).json({ message: err.message });
  }
});

app.listen(port, () => {
  console.log(`http://localhost:${port}`);
});

image

source: mike-demo-project

createESTest(input, type, message)

• Get clear, actionable bug reports (for library authors/maintainers).

import { createESTest } from "escss-estest";

// Encapsulate createESTest to provide your library's own default message
function ESTest(
  input,
  type,
  message = "[libraryName] your message for others to help debugging",
) {
  return createESTest(input, type, message);
}

Auxiliary API

globalThis.__ESCSS_ESTEST__.information

• Show library information

globalThis.__ESCSS_ESTEST__.message

• Captures internal bug reports (for company teams)

// Set in the entry point, e.g., main.js, App.vue, or App.jsx...
globalThis.__ESCSS_ESTEST__.message = "Please report this issue to ...";

globalThis.__ESCSS_ESTEST__.isESTestDisabled

• Why have this feature?

  • Avoids vendor lock-in for long-term project flexibility.
  • Optimizes production performance by enabling in dev and disabling in prod.

  Note: unSafeESTest will not be affected (for security reasons)

globalThis.__ESCSS_ESTEST__.isESTestDisabled = true;

function sum(a, b) {
  {
    ESTest(a, "number");
    ESTest(b, "number");
  }

  return a + b;
}

// same as below
function sum(a, b) {
  return a + b;
}

globalThis.__ESCSS_ESTEST__.analysis

• Show usage reports