tguard-js
    Preparing search index...

    tguard-js

    tguard-js

    GitHub Actions Test Codecov Coverage CodeFactor
    npm version npm bundle size TypeScript License
    Node Version Bun Support

    A lightweight, runtime-agnostic validation library designed to secure the boundaries of your application. It delivers strict runtime type narrowing, absolute cross-realm safety, and predictable edge-case handling where TypeScript compile-time inferences cannot reach.

    Unlike heavy validation libraries, this package eliminates the boilerplate of writing repetitive runtime type checks. It provides a consistent, high-performance utility set so you can focus on building your application instead of rewriting the same guards.

    Core Benefit Why It Matters Perfect Use Cases
    Zero External Dependencies Keeps your final bundle size minimal and completely eliminates supply-chain security risks. CLI Tools & SDKs: Maintainers looking to build lean, ultra-fast utilities with no downstream bloat.
    Runtime Agnostic Seamlessly works across Node.js (v14.13+), modern browsers, Bun, and other contemporary JS environments. Isomorphic Applications: Monorepos sharing validation logic between backends and frontends.
    Predictable Structural Shapes Uses hasShape to explicitly validate object structures and nested properties with well-defined behavior. Web Scrapers & Config Parsers: Safely asserting the exact keys and types of messy, extracted data or incoming user configurations.
    Cross-Realm Safe Accurately checks types across isolated execution contexts where native features like instanceof shatter. Micro-frontends & Workers: Environments passing dynamic payloads across Iframes or Web Worker boundaries.
    TypeScript Inference Uses precise value is T type predicates to unlock instant IDE autocomplete and compile-time type narrowing. REST APIs & Route Guards: Transforming untyped, incoming unknown JSON bodies into strictly typed objects.

    JavaScript’s built-in type checks are inconsistent and sometimes misleading.

    // Cross-realm issue
    const ForeignError = window.frames[0].Error;
    new ForeignError() instanceof Error; // false

    // Primitive coercion (by spec, but often undesirable)
    Object.isSealed(null);     // true
    Object.isFrozen(123);      // true
    typeof null === 'object';  // true

    These results are technically correct by specification, but not useful for runtime validation.

    import tg from 'tguard-js';

    tg.isNull(null);    // true
    tg.isArray([]);     // true
    tg.isObject(null);  // false
    tg.isRecord({});    // true
    tg.isRecord([]);    // false

    // Cross-realm safe
    const ForeignError = window.frames[0].Error;
    tg.isError(new ForeignError()); // true

    // Predictable object checks
    tg.isSealed(null);  // false
    tg.isFrozen(123);   // false
    tg.utils.getType(null, true) === 'object'; // false

    The library prioritizes predictability over spec quirks.

    bun a tguard-js

    npm i tguard-js

    tguard-js supports both ESModule and CommonJS modules.

    import tg from 'tguard-js';

    const tg = require('tguard-js');

    import { isString, isArrayOf, isRecord } from 'tguard-js';

    // Basic validation
    if (isString(value)) {
      value.toUpperCase();
    }

    // Check if all array elements are string
    if (isArrayOf(data, isString)) {
      console.log(data[0]);
    }

    // Check if the config has `key` property before consuming it
    if (isRecord(config) && isString(config.key)) {
      useConfig(config);
    }

    Object validation:

    import tg from 'tguard-js';

    const isUser = (u) => tg.hasShape(u, {
      id: tg.isNumber,
      name: tg.isString,
    });

    const data = { ... } // untrusted user data

    // Check if the input is unrecognized as user data
    if (!isUser(data)) {
      // Here you can throw an error or have a fallback
    }

    // Can safely use the input data
    consumeUser(data);

    See APIs documentation:
    → API Overview

    More patterns and examples:
    → Advanced Usage

    bun run test

    or:

    npm run test

    The test suite covers:

    • edge cases
    • invalid inputs
    • runtime consistency

    Contributions are welcome and appreciated. Please prefer small, focused changes with clear context and reasoning whenever possible.

    Before opening a pull request, read the CONTRIBUTING.md guide for setup instructions, development workflow, and contribution guidelines.

    © 2026 Ryuu Mitsuki. Licensed under the MIT License.

    Made with ❤️ by developer, for developers.

    Settings

    Member Visibility

    On This Page

    tguard-js