{"id":16003010,"url":"https://github.com/jacobgardner/ts-audit","last_synced_at":"2025-09-11T18:41:40.619Z","repository":{"id":44159343,"uuid":"173202078","full_name":"jacobgardner/ts-audit","owner":"jacobgardner","description":"Runtime validation of TypeScript interfaces","archived":false,"fork":false,"pushed_at":"2022-02-11T16:42:26.000Z","size":521,"stargazers_count":4,"open_issues_count":32,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-08T07:51:48.704Z","etag":null,"topics":["json-schema","schema","transformer-typescript","typescript","validation"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jacobgardner.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-02-28T23:18:24.000Z","updated_at":"2021-10-10T18:43:23.000Z","dependencies_parsed_at":"2022-09-05T13:51:09.000Z","dependency_job_id":null,"html_url":"https://github.com/jacobgardner/ts-audit","commit_stats":null,"previous_names":["jacobgardner/ts-runtime-interface"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/jacobgardner/ts-audit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacobgardner%2Fts-audit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacobgardner%2Fts-audit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacobgardner%2Fts-audit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacobgardner%2Fts-audit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jacobgardner","download_url":"https://codeload.github.com/jacobgardner/ts-audit/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacobgardner%2Fts-audit/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264925876,"owners_count":23684222,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["json-schema","schema","transformer-typescript","typescript","validation"],"created_at":"2024-10-08T10:05:42.499Z","updated_at":"2025-07-20T19:32:48.748Z","avatar_url":"https://github.com/jacobgardner.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TS-AUDIT\n\n[![Build\nStatus](https://travis-ci.com/jacobgardner/ts-audit.svg?branch=master)](https://travis-ci.com/jacobgardner/ts-audit)\n\n`ts-audit` is a Typescript transform plugin that verifies external data\nstructures match what you expect them to be inside your typescript ecosystem.\n\nTypescript's safety guarentees can only work on data that originated inside your\ncode. Performing a type assertion on a JSON object downloaded from an external\nAPI or library can lead to odd, hard to debug, runtime errors that Typescript\nwould otherwise have prevented at compile time. `ts-audit` solves that by\nverifying that external data structures match the structure of the types inside\nyour system before you can start to interact with them. What this provides is a\nbarrier between your safe and unsafe code and clearly shows when untyped data\ndoesn't match your expections. We can't stop mismatched expectations from\noccurring at runtime, but we can do is isolate where they can occur and provide\nclear indicators of where a mismatch occured and why.\n\n## Before Using\n\nPlease read and understand the known issues before consuming. We're working to\nfix these issues, but in the meantime, you may have to adapt your project's\nworkflow to utilize this project effectively.\n\n## Installation\n\nYou'll need to install two packages, `ts-audit` and `ttypescript` which is used\nto run the transform plugin. (You'll still need `typescript` as `ttypescript`\nuses whatever version of `typescript` you have installed)\n\n    npm install --save-dev ts-audit ttypescript\n\nYour `tsconfig.json` will need to be modified to use `ts-audit` during the\ncompilation process.\n\n```javascript\n{\n    \"compilerOptions\": {\n        /* Basic Options */\n        \"plugins\": [\n            {\n                \"transform\": \"ts-audit\",\n            }\n        ],\n        /* ... */\n    }\n}\n```\n\nFinally, you'll need to change your build setup to use `ttsc` instead of `tsc`.\n\nAnd you're ready to go!!!!!!\n\n## Usage\n\nAll you have to do to use `ts-audit` is use `assertIsType` or `isType` from the library, making sure to annotate the type of the assigned value.\n\n```typescript\nimport { assertIsType } from 'ts-audit';\n\nenum Animal {\n    Cat = 'cat',\n    Dog = 'dog',\n    Goat = 'goat',\n}\n\ninterface UserData {\n    username: string;\n    phoneNumber: string;\n    age: number;\n    pet: Animal;\n    notes?: string;\n}\n\nconst fredsData: UserData = assertIsType(await fetchUser('fred'));\n\nconst rawData: unknown = await fetchUser('jake');\nif (isType\u003cUserData\u003e(rawData)) {\n    // rawData is typeGuarded as UserData if true\n    assert(rawData.username === 'jake');\n}\n```\n\nIn this example `fetchUser` hits an API that returns a JSON object that we\nexpect to match UserData. If the object matches correctly, then we can use it\nsafely in our system using the power of the typescript type-system. If there's\na mispelling, missing required key, or type-mismatch we'll throw a runtime error\nindicating that the JSON returned does not match what we were expecting.\n\n## Limitations\n\nThis does not work for classes, functions, or pretty much anything else that's\nnot supported by JSON-schema. The type sent to validateFunction must be a\nconcrete type. This will NOT work if given a generic argument. ALSO, this has\nonly been tested in a node environment. This may require some additional work to\nget it working in the browser, but it should be pretty close already if not.\nJSON schema allow some forms of validation (such as string length) that this\ntool currently does not.\n\n## Known Issues\n\nThese are some known issues. There may be more unknown...\n\n-   This does not support primitive types unless they are aliased.\n-   Importing as a named import is the only way to currently interact with\n    `ts-audit`.\n-   Watch mode does not appear to work correctly on the consuming project when\n    altering code using the `ts-audit` library.\n-   The validations file does not update properly when using `incremental` mode.\n-   There appear to be `typechecker` issues when using ts-node.\n    -   If you wish to test your project using something like mocha, then instead\n        of relying on ts-node, you can build a tsconfig.test.json (if necessary) or\n        just use `ttsc --outDir=.test` and then run your test framework from there.\n        For example: `ttsc --outDir=.test \u0026\u0026 nyc mocha --reporter=dot \".test/**/*.spec.js\"`\n\n## Other Similar Projects\n\n-   [typescript-is](https://github.com/woutervh-/typescript-is) - This project\n    currently only supports inline validations which means it replaces your\n    validation calls with conditionals checking in-line with your code. This\n    _MAY_ lead to more performant checking. I want to do some performance\n    analysis/code gen analysis against this project at some point.\n-   There are some code-gen tools that will take somelike like a Swagger or API\n    Blueprint doc and generate typescript interfaces in your codebase; Then use\n    swagger validate to validate against the API. If you're using Swagger or\n    similar API documentation framework to drive out your serialized structures,\n    then this is probably a better way to go.\n\n## Directory Structure\n\nOverview of the project via directory structure. May help you understand how\nthe code works.\n\n-   `/src` - Source for the transformer\n    -   `/src/astGenerators` - Functions that generate the AST to be output in the runtime.\n    -   `/src/utils` - Various utilities for making code more DRY and readable. This needs some love.\n    -   `/src/transforms` - The code that transforms that validation calls inline to use the runtime.\n    -   `/src/buildRuntimeValidator.ts` - Given the schema definitions, this is responsible\n        for actually building the generated javascript file used.\n    -   `/src/config.ts` - Global configuration values that should eventually be made user-config.\n    -   `/src/errors.ts` - Util for building up user-friendly error list for compile-time issues\n        from `ts-audit` that typescript doesn't report.\n    -   `/src/main.ts` - Entry point for typescript compiler to invoke the transformer\n    -   `/src/schemaDB.ts` - Class that contains all definitions of types being runtime-checked.\n        Ultimately dumps the schema definition list to the runtime.\n    -   `/src/validationVisitor.ts` - The code which visits all the nodes\n        attemping to find `ts-audit` functions/imports and transforming them correctly.\n-   `/tests` - Tests testing the transformer and schema validation\n    -   `/tests/valid` - Tests that build and run to completion (including testing bad schemas)\n    -   `/tests/invalid` - A series of files that should fail at build time.\n\n## Running Tests\n\n    npm test\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjacobgardner%2Fts-audit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjacobgardner%2Fts-audit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjacobgardner%2Fts-audit/lists"}