npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@mutoe/ts-auto-guard

v5.0.1-2

Published

Generate type guard functions from TypeScript interfaces

Downloads

14

Readme

ts-auto-guard

Forked from rhys-vdw/ts-auto-guard

Added support for assert mode. See TypeScript 3.7 for more info.

ts-auto-guard --assert

NPM Version Test

Generate type guard functions from TypeScript interfaces

A tool for automatically generating TypeScript type guards for interfaces in your code base.

This tool aims to allow developers to verify data from untyped sources to ensure it conforms to TypeScript types. For example when initializing a data store or receiving structured data in an AJAX response.

Install

Yarn

yarn add -D ts-auto-guard

npm

npm install --save-dev ts-auto-guard

TypeScript configuration

It makes sense to use this library in strict mode. Make sure to turn on the strict mode family options by defining "strict": true in tsconfig.json under compilerOptions. If you have any problems check that strict mode family options, such as strictNullChecks, are not explicitly set to false. Check these issues for more info.

Usage

Specify which types to process (see below) and run the CLI tool in the same folder as your project's tsconfig.json (optionally passing in paths to the files you'd like it to parse).

ts-auto-guard ./my-project/Person.ts

See generated files alongside your annotated files:

// my-project/Person.guard.ts

import { Person } from './Person'

export function isPerson(obj: unknown): obj is Person {
  const typedObj = obj as Person
  return (
    typeof typedObj === 'object' &&
    typeof typedObj['name'] === 'string' &&
    (typeof typedObj['age'] === 'undefined' ||
      typeof typedObj['age'] === 'number') &&
    Array.isArray(typedObj['children']) &&
    typedObj['children'].every(e => isPerson(e))
  )
}

Now use in your project:

// index.ts

import { Person } from './Person'
import { isPerson } from './Person.guard'

// Loading up an (untyped) JSON file
const person = require('./person.json')

if (isPerson(person)) {
  // Can trust the type system here because the object has been verified.
  console.log(`${person.name} has ${person.children.length} child(ren)`)
} else {
  console.error('Invalid person.json')
}

Specifying which types to process

Specify with annotation

Annotate interfaces in your project. ts-auto-guard will generate guards only for interfaces with a @see {name} ts-auto-guard:type-guard JSDoc @see tag.

// my-project/Person.ts

/** @see {isPerson} ts-auto-guard:type-guard */
export interface Person {
  // !do not forget to export - only exported types are processed
  name: string
  age?: number
  children: Person[]
}

The JSDoc @link tag is also supported: @see {@link name} ts-auto-guard:type-guard.

Process all types

Use --export-all parameter to process all exported types:

ts-auto-guard --export-all 'src/domain/*.ts'

Debug mode

Use debug mode to help work out why your type guards are failing in development. This will change the output type guards to log the path, expected type and value of failing guards.

ts-auto-guard --debug
isPerson({ name: 20, age: 20 })
// stderr: "person.name type mismatch, expected: string, found: 20"

Short circuiting

ts-auto-guard also supports a shortcircuit flag that will cause all guards to always return true.

ts-auto-guard --shortcircuit="process.env.NODE_ENV === 'production'"

This will result in the following:

// my-project/Person.guard.ts

import { Person } from './Person'

export function isPerson(obj: unknown): obj is Person {
  if (process.env.NODE_ENV === 'production') {
    return true
  }
  const typedObj = obj as Person
  return (
    typeof typedObj === 'object' &&
    // ...normal conditions
  )
}

Using the shortcircuit option in combination with uglify-js's dead_code and global_defs options will let you omit the long and complicated checks from your production code.

Change Guard File Name

ts-auto-guard will create a .guard.ts file by default, but this can be overriden.

ts-auto-guard --guard-file-name="debug"

Will result in a guard file called .debug.ts.

Add Import to Source File

ts-auto-guard supports an ìmport-guards flag. This flag will add an import statement at the top and a named export at the bottom of the source files for the generated type guards. The ìmport-guards flag also optionally accepts a custom name for the import alias, if none is passed then TypeGuards is used as a default.

If you would like to override the default behavior and not have the type guards exported from source use the prevent-export-imported flag with the import-guards flag.

ts-auto-guard --import-guards="Guards"

Will result in the following being added to your source code.

// my-project/Person.ts

import * as Guards from './Person.guard'

/** The rest of your source code */

export { Guards }

Add Custom File Extension to Import Statements

By default, the import statements in generated files won't have any extension. However, this doesn't work with ESM, which requires .js extension for import statements.

ts-auto-guard supports an import-extension flag to set a custom extension in import statements:

ts-auto-guard --import-extension="js"

This will result in the following:

// my-project/Person.guard.ts

import { Person } from './Person.js'

export function isPerson(obj: unknown): obj is Person {
  if (process.env.NODE_ENV === 'production') {
    return true
  }
  const typedObj = obj as Person
  return (
    typeof typedObj === 'object' &&
    // ...normal conditions
  )
}