tstyche 1.0.0-beta.0

package/LICENSE.md

@@ -0,0 +1,10 @@
+# MIT License
+
+Copyright © 2023-present TSTyche
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# TSTyche
+
+[![license][license-src]][license-href]
+
+The Essential Type Testing Tool.
+
+---
+
+TSTyche is a type testing tool for TypeScript. It ships with `describe()` and `test()` helpers, `expect` style assertions and a mighty test runner.
+
+## Helpers
+
+If you are used to test JavaScript, a simple type test file should look familiar:
+
+```ts
+import { expect, test } from "tstyche";
+
+function firstItem<T>(target: Array<T>): T | undefined {
+  return target[0];
+}
+
+test("firstItem", () => {
+  expect(firstItem(["a", "b", "c"])).type.toEqual<string | undefined>();
+
+  expect(firstItem()).type.toRaiseError("Expected 1 argument");
+});
+```
+
+To organize, debug and plan tests TSTyche has:
+
+- `test()`, `it()`, `describe()` and `context()` helpers;
+- with `.only`, `.skip` and `.todo` run mode flags.
+
+## Assertions
+
+The assertions can be used to write type tests (like in the above example) or mixed in your functional tests:
+
+```ts
+import * as tstyche from "tstyche";
+
+function secondItem<T>(target: Array<T>): T | undefined {
+  return target[1];
+}
+
+describe("secondItem", () => {
+  it("should handle numbers", () => {
+    expect(secondItem([1, 2, 3])).toBe(1);
+
+    tstyche.expect(secondItem([1, 2, 3])).type.toEqual<number | undefined>();
+  });
+});
+```
+
+Here is the list of all matchers:
+
+- `.toBeAssignable()`, `.toEqual()`, `.toMatch()` compares types or types of expression;
+- `.toRaiseError()` captures the error message or code;
+- `.toBeString()`, `.toBeNumber()`, `.toBeVoid()` and 9 more checks for primitive types.
+
+## Runner
+
+The `tstyche` command is the heart of TSTyche. For example, it can select test files by path, filter tests by name and pass them through TypeScript `4.8` and `latest`:
+
+```sh
+tstyche JsonObject --only external --target 4.8,latest
+```
+
+This simple!
+
+## Documentation
+
+Visit [https://tstyche.org][documentation-href] to view the full documentation.
+
+## License
+
+[MIT][license-href] © TSTyche
+
+[documentation-href]: https://tstyche.org
+[license-src]: https://badgen.net/github/license/tstyche/tstyche
+[license-href]: https://github.com/tstyche/tstyche/blob/main/LICENSE.md

package/build/bin.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { Cli } from './tstyche.js';
+
+const cli = new Cli(process);
+await cli.run(process.argv.slice(2));

package/build/index.d.ts

@@ -0,0 +1,276 @@
+interface Describe {
+    /**
+     * Defines a group of tests.
+     *
+     * @param name - The name of the group.
+     * @param callback - The function to create a scope for a group of tests.
+     */
+    (name: string, callback: () => void | Promise<void>): void;
+    /**
+     * Marks a group of tests as focused.
+     *
+     * @param name - The name of the group.
+     * @param callback - The function to create a scope for a group of tests.
+     */
+    only: (name: string, callback: () => void | Promise<void>) => void;
+    /**
+     * Marks a group of tests as skipped.
+     *
+     * @param name - The name of the group.
+     * @param callback - The function to create a scope for a group of tests.
+     */
+    skip: (name: string, callback: () => void | Promise<void>) => void;
+    /**
+     * Marks a group of tests as yet to be implemented.
+     *
+     * @param name - The name of the group.
+     * @param callback - The function to create a scope for a group of tests.
+     */
+    todo: (name: string, callback?: () => void | Promise<void>) => void;
+}
+interface Test {
+    /**
+     * Defines a single test.
+     *
+     * @param name - The name of the test.
+     * @param callback - The function with a code snippet and assertions.
+     */
+    (name: string, callback: () => void | Promise<void>): void;
+    /**
+     * Marks a test as focused.
+     *
+     * @param name - The name of the test.
+     * @param callback - The function with a code snippet and assertions.
+     */
+    only: (name: string, callback: () => void | Promise<void>) => void;
+    /**
+     * Marks a test as skipped.
+     *
+     * @param name - The name of the test.
+     * @param callback - The function with a code snippet and assertions.
+     */
+    skip: (name: string, callback: () => void | Promise<void>) => void;
+    /**
+     * Marks a test as yet to be implemented.
+     *
+     * @param name - The name of the test.
+     * @param callback - The function with a code snippet and assertions.
+     */
+    todo: (name: string, callback?: () => void | Promise<void>) => void;
+}
+interface Matchers {
+    /**
+     * Checks if the source type is `any`.
+     */
+    toBeAny: () => void;
+    /**
+     * Checks if the target type is assignable to the source type.
+     */
+    toBeAssignable: {
+        /**
+         * Checks if the target type is assignable to the source type.
+         */
+        <Target>(): void;
+        /**
+         * Checks if type of the target expression is assignable to the source type.
+         */
+        (target: unknown): void;
+    };
+    /**
+     * Checks if the source type is `bigint`.
+     */
+    toBeBigInt: () => void;
+    /**
+     * Checks if the source type is `boolean`.
+     */
+    toBeBoolean: () => void;
+    /**
+     * Checks if the source type is `never`.
+     */
+    toBeNever: () => void;
+    /**
+     * Checks if the source type is `null`.
+     */
+    toBeNull: () => void;
+    /**
+     * Checks if the source type is `number`.
+     */
+    toBeNumber: () => void;
+    /**
+     * Checks if the source type is `string`.
+     */
+    toBeString: () => void;
+    /**
+     * Checks if the source type is `symbol`.
+     */
+    toBeSymbol: () => void;
+    /**
+     * Checks if the source type is `undefined`.
+     */
+    toBeUndefined: () => void;
+    /**
+     * Checks if the source type is `unique symbol`.
+     */
+    toBeUniqueSymbol: () => void;
+    /**
+     * Checks if the source type is `unknown`.
+     */
+    toBeUnknown: () => void;
+    /**
+     * Checks if the source type is `void`.
+     */
+    toBeVoid: () => void;
+    /**
+     * Check if the target type is identical to the source type.
+     */
+    toEqual: {
+        /**
+         * Checks if the target type is identical to the source type.
+         */
+        <Target>(): void;
+        /**
+         * Checks if type of the target expression is identical to the source type.
+         */
+        (target: unknown): void;
+    };
+    /**
+     * Checks if the target type is a subtype the source type.
+     */
+    toMatch: {
+        /**
+         * Checks if the target type is a subtype the source type.
+         */
+        <Target>(): void;
+        /**
+         * Checks if type of the target expression is a subtype the source type.
+         */
+        (target: unknown): void;
+    };
+    /**
+     * Checks if the source type raises an error.
+     */
+    toRaiseError: (...target: Array<string | number>) => void;
+}
+interface Modifier {
+    /**
+     * Passes the source type to the matcher.
+     */
+    type: Matchers & {
+        /**
+         * Negates the assertion.
+         */
+        not: Matchers;
+    };
+}
+interface Expect {
+    /**
+     * Builds an assertion.
+     *
+     * @typeParam Source - The type against which the assertion will be made.
+     */
+    <Source>(): Modifier;
+    /**
+     * Builds an assertion.
+     *
+     * @param source - The expression against which type the assertion will be made.
+     */
+    (source: unknown): Modifier;
+    fail: {
+        /**
+         * Mark an assertion as supposed to fail.
+         *
+         * @typeParam Source - The type against which the assertion will be made.
+         */
+        <Source>(): Modifier;
+        /**
+         * Mark an assertion as supposed to fail.
+         *
+         * @param source - The expression against which type the assertion will be made.
+         */
+        (source: unknown): Modifier;
+    };
+    /**
+     * Marks an assertion as focused.
+     */
+    only: {
+        /**
+         * Marks an assertion as focused.
+         *
+         * @typeParam Source - The type against which the assertion will be made.
+         */
+        <Source>(): Modifier;
+        /**
+         * Marks an assertion as focused.
+         *
+         * @param source - The expression against which type the assertion will be made.
+         */
+        (source: unknown): Modifier;
+        fail: {
+            /**
+             * Mark an assertion as supposed to fail.
+             *
+             * @typeParam Source - The type against which the assertion will be made.
+             */
+            <Source>(): Modifier;
+            /**
+             * Mark an assertion as supposed to fail.
+             *
+             * @param source - The expression against which type the assertion will be made.
+             */
+            (source: unknown): Modifier;
+        };
+    };
+    /**
+     * Marks an assertion as skipped.
+     */
+    skip: {
+        /**
+         * Marks an assertion as skipped.
+         *
+         * @typeParam Source - The type against which the assertion will be made.
+         */
+        <Source>(): Modifier;
+        /**
+         * Marks an assertion as skipped.
+         *
+         * @param source - The expression against which type the assertion will be made.
+         */
+        (source: unknown): Modifier;
+        fail: {
+            /**
+             * Marks an assertion as supposed to fail.
+             *
+             * @typeParam Source - The type against which the assertion will be made.
+             */
+            <Source>(): Modifier;
+            /**
+             * Marks an assertion as supposed to fail.
+             *
+             * @param source - The expression against which type the assertion will be made.
+             */
+            (source: unknown): Modifier;
+        };
+    };
+}
+/**
+ * Defines a test group.
+ */
+declare const describe: Describe;
+/**
+ * Defines a test group.
+ */
+declare const context: Describe;
+/**
+ * Defines a single test.
+ */
+declare const test: Test;
+/**
+ * Defines a single test.
+ */
+declare const it: Test;
+/**
+ * Builds an assertion.
+ */
+declare const expect: Expect;
+
+export { context, describe, expect, it, test };

package/build/index.js

@@ -0,0 +1,12 @@
+function doNothing() {
+}
+const noopChain = new Proxy(doNothing, {
+    apply() {
+        return noopChain;
+    },
+    get() {
+        return noopChain;
+    },
+});
+
+export { noopChain as context, noopChain as describe, noopChain as expect, noopChain as it, noopChain as test };