{"id":15017383,"url":"https://github.com/cartant/ts-snippet","last_synced_at":"2025-04-11T14:44:17.391Z","repository":{"id":55985209,"uuid":"105356493","full_name":"cartant/ts-snippet","owner":"cartant","description":"A TypeScript snippet compiler for any test framework","archived":false,"fork":false,"pushed_at":"2024-05-08T08:45:50.000Z","size":1019,"stargazers_count":33,"open_issues_count":6,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-10-18T08:09:21.664Z","etag":null,"topics":["ava","jasmine","jest","mocha","snippet","tape","typescript"],"latest_commit_sha":null,"homepage":"https://cartant.github.io/ts-snippet/","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/cartant.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["cartant"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2017-09-30T08:48:42.000Z","updated_at":"2024-10-17T05:40:06.000Z","dependencies_parsed_at":"2024-06-18T20:04:44.113Z","dependency_job_id":"a832fcb6-f048-4b49-bf42-061c8ffd2cdb","html_url":"https://github.com/cartant/ts-snippet","commit_stats":{"total_commits":180,"total_committers":4,"mean_commits":45.0,"dds":0.07222222222222219,"last_synced_commit":"5745eb208fd6b158a4593efe37b9d01355188f85"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cartant%2Fts-snippet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cartant%2Fts-snippet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cartant%2Fts-snippet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cartant%2Fts-snippet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cartant","download_url":"https://codeload.github.com/cartant/ts-snippet/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248420718,"owners_count":21100454,"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":["ava","jasmine","jest","mocha","snippet","tape","typescript"],"created_at":"2024-09-24T19:50:23.251Z","updated_at":"2025-04-11T14:44:17.373Z","avatar_url":"https://github.com/cartant.png","language":"TypeScript","funding_links":["https://github.com/sponsors/cartant"],"categories":[],"sub_categories":[],"readme":"# ts-snippet\n\n[![GitHub License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/cartant/ts-snippet/blob/master/LICENSE)\n[![NPM version](https://img.shields.io/npm/v/ts-snippet.svg)](https://www.npmjs.com/package/ts-snippet)\n[![Build status](https://img.shields.io/travis/cartant/ts-snippet.svg)](http://travis-ci.org/cartant/ts-snippet)\n[![dependency status](https://img.shields.io/david/cartant/ts-snippet.svg)](https://david-dm.org/cartant/ts-snippet)\n[![devDependency Status](https://img.shields.io/david/dev/cartant/ts-snippet.svg)](https://david-dm.org/cartant/ts-snippet#info=devDependencies)\n[![peerDependency Status](https://img.shields.io/david/peer/cartant/ts-snippet.svg)](https://david-dm.org/cartant/ts-snippet#info=peerDependencies)\n[![Greenkeeper badge](https://badges.greenkeeper.io/cartant/ts-snippet.svg)](https://greenkeeper.io/)\n\n### What is it?\n\n`ts-snippet` is a TypeScript snippet compiler for any test framework.\n\nIt does not run the compiled snippets. Instead, it provides assertion methods that can be used to test the TypeScript programs compiled from the snippets. However, if you've not yet started writing tests for your TypeScript types, you should look at using [`tsd`](https://github.com/SamVerschueren/tsd) instead.\n\n### Why might you need it?\n\nI created the `ts-snippet` package out of the need to test overloaded TypeScript functions that have many overload signatures.\n\nThe order in which overload signatures are specified is critical and the most specific overloads need to be placed first - as TypeScript will match the first compatible overload signature.\n\nWithout using `ts-snippet`, it's simple to write tests that establish whether or not TypeScript code compiles, but it's more difficult to write tests that establish whether type inferences are correct (especially when `any` is involved) or whether types are intentionally incompatible (and generate compilation errors).\n\n`ts-snippet` includes assertions that will verify whether inferred types are what's expected and whether compilation succeeds or fails.\n\nIf you need to perform similar assertions, you might find `ts-snippet` useful.\n\nFor an example of how `ts-snippet` can be used to write tests, checkout the [`research-spec.ts`](https://github.com/cartant/ts-action/blob/v2.0.2/source/research-spec.ts) file in my `ts-action` repo.\n\n## Install\n\nInstall the package using npm:\n\n```\nnpm install ts-snippet --save-dev\n```\n\n## Usage\n\nThis simplest way to use `ts-snippet` is to create a snippet expectation function using `expecter`:\n\n```ts\nimport { expecter } from \"ts-snippet\";\n\nconst expectSnippet = expecter();\n\ndescribe(\"observables\", () =\u003e {\n  it(\"should infer the source's type\", () =\u003e {\n    expectSnippet(`\n      import * as Rx from \"rxjs\";\n      const source = Rx.Observable.of(1);\n    `).toInfer(\"source\", \"Observable\u003cnumber\u003e\");\n  });\n});\n```\n\n`expecter` can be passed a factory so that common imports can be specified in just one place. For example:\n\n```ts\nimport { expecter } from \"ts-snippet\";\n\nconst expectSnippet = expecter(code =\u003e `\n  import * as Rx from \"rxjs\";\n  ${code}\n`);\n\ndescribe(\"observables\", () =\u003e {\n  it(\"should infer the source's type\", () =\u003e {\n    expectSnippet(`\n      const source = Rx.Observable.of(1);\n    `).toInfer(\"source\", \"Observable\u003cnumber\u003e\");\n  });\n});\n```\n\nAlternatively, the package exports a `snippet` function that returns a `Snippet` instance, upon which assertions can be made.\n\nThe `snippet` function takes an object containing one or more files - with the keys representing the file names and the values the file content (as strings). The function also takes an optional `Compiler` instance - if not specified, a `Compiler` instance is created within the `snippet` call. With snippets that import large packages (such as RxJS) re-using the compiler can effect significant performance gains.\n\nUsing Mocha, the tests look something like this:\n\n```ts\nimport { Compiler, snippet } from \"ts-snippet\";\n\ndescribe(\"observables\", () =\u003e {\n\n  let compiler: Compiler;\n\n  before(() =\u003e {\n    compiler = new Compiler();\n  });\n\n  it(\"should infer the source's type\", () =\u003e {\n    const s = snippet({\n      \"snippet.ts\": `\n        import * as Rx from \"rxjs\";\n        const source = Rx.Observable.of(1);\n      `\n    }, compiler);\n    s.expect(\"snippet.ts\").toInfer(\"source\", \"Observable\u003cnumber\u003e\");\n  });\n\n  it(\"should infer the mapped type\", () =\u003e {\n    const s = snippet({\n      \"snippet.ts\": `\n        import * as Rx from \"rxjs\";\n        const source = Rx.Observable.of(1);\n        const mapped = source.map(x =\u003e x.toString());\n      `\n    }, compiler);\n    s.expect(\"snippet.ts\").toInfer(\"mapped\", \"Observable\u003cstring\u003e\");\n  });\n});\n```\n\nCompiler can be passed the TypeScript `compilerOptions` JSON configuration and root directory for relative path module resolution (defaults to `process.cwd()`).\n```ts\nnew Compiler({\n  strictNullChecks: true\n}, __dirname); // Now module paths will be relative to the directory where the test file is located.\n```\n\nIf the BDD-style expectations are not to your liking, there are alternate methods that are more terse.\n\nWhen using `ts-snippet` with AVA or tape, the import should specify the specific subdirectory so that the appropriate assertions are configured and the assertions count towards the test runner's plan.\n\nUsing the tape-specific import and terse assertions, tests would look something like this:\n\n```ts\nimport * as tape from \"tape\";\nimport { snippet } from \"ts-snippet/tape\";\n\ntape(\"should infer Observable\u003cnumber\u003e\", (t) =\u003e {\n  t.plan(1);\n  const s = snippet(t, {\n    \"snippet.ts\": `\n      import * as Rx from \"rxjs\";\n      const source = Rx.Observable.from([0, 1]);\n    `\n  });\n  s.infer(\"snippet.ts\", \"source\", \"Observable\u003cnumber\u003e\");\n});\n```\n\nFor an example of how `ts-snippet` can be used, have a look at [these tests](https://github.com/cartant/ts-action/blob/master/source/research-spec.ts) in `ts-action`.\n\n## API\n\n```ts\nfunction expecter(\n  factory: (code: string) =\u003e string = code =\u003e code,\n  compilerOptions?: object,\n  rootDirectory?: string\n): (code: string) =\u003e Expect;\n\nfunction snippet(\n  files: { [fileName: string]: string },\n  compiler?: Compiler\n): Snippet;\n```\n\n```ts\ninterface Snippet {\n  fail(fileName: string, expectedMessage?: RegExp): void;\n  expect(fileName: string): Expect;\n  infer(fileName: string, variableName: string, expectedType: string): void;\n  succeed(fileName: string): void;\n}\n\ninterface Expect {\n  toFail(expectedMessage?: RegExp): void;\n  toInfer(variableName: string, expectedType: string): void;\n  toSucceed(): void;\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcartant%2Fts-snippet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcartant%2Fts-snippet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcartant%2Fts-snippet/lists"}