From b176dd938fdb75525d84bffb153ee02d8f43cd54 Mon Sep 17 00:00:00 2001 From: unional Date: Sat, 10 Oct 2026 20:12:54 -0700 Subject: [PATCH 1/2] feat(website): add the t+ logo and favicon The logo is a lowercase t whose crossbar runs on into a plus. It replaces the "tp" script-font logo and Starlight's default favicon, and heads both readmes. A <+> pair is kept in assets/backup. Co-Authored-By: Claude Opus 5.5 --- apps/website/public/favicon.svg | 2 +- .../src/assets/backup/type-plus-brackets-tile.svg | 1 + apps/website/src/assets/backup/type-plus-brackets.svg | 1 + apps/website/src/assets/type-plus.svg | 10 +--------- packages/type-plus/readme.md | 2 ++ readme.md | 2 ++ 6 files changed, 8 insertions(+), 10 deletions(-) create mode 100644 apps/website/src/assets/backup/type-plus-brackets-tile.svg create mode 100644 apps/website/src/assets/backup/type-plus-brackets.svg diff --git a/apps/website/public/favicon.svg b/apps/website/public/favicon.svg index 211ab02544..757c4735ae 100644 --- a/apps/website/public/favicon.svg +++ b/apps/website/public/favicon.svg @@ -1 +1 @@ -type-plus \ No newline at end of file +type-plus diff --git a/apps/website/src/assets/backup/type-plus-brackets-tile.svg b/apps/website/src/assets/backup/type-plus-brackets-tile.svg new file mode 100644 index 0000000000..ea8b244f40 --- /dev/null +++ b/apps/website/src/assets/backup/type-plus-brackets-tile.svg @@ -0,0 +1 @@ +type-plus diff --git a/apps/website/src/assets/backup/type-plus-brackets.svg b/apps/website/src/assets/backup/type-plus-brackets.svg new file mode 100644 index 0000000000..9467b559d2 --- /dev/null +++ b/apps/website/src/assets/backup/type-plus-brackets.svg @@ -0,0 +1 @@ +type-plus diff --git a/apps/website/src/assets/type-plus.svg b/apps/website/src/assets/type-plus.svg index 135c8103af..4df493b677 100644 --- a/apps/website/src/assets/type-plus.svg +++ b/apps/website/src/assets/type-plus.svg @@ -1,9 +1 @@ - - type-plus - - tp - - - - - +type-plus diff --git a/packages/type-plus/readme.md b/packages/type-plus/readme.md index a70e00bb0f..6c34251479 100644 --- a/packages/type-plus/readme.md +++ b/packages/type-plus/readme.md @@ -1,3 +1,5 @@ +type-plus logo + # type-plus [![NPM version][npm_image]][npm_url] diff --git a/readme.md b/readme.md index 076aa3cd3f..260396c190 100644 --- a/readme.md +++ b/readme.md @@ -1,3 +1,5 @@ +type-plus logo + # type-plus [![NPM version][npm_image]][npm_url] From ebf3d94986204899a81647bfea562c697e0a65b6 Mon Sep 17 00:00:00 2001 From: unional Date: Sat, 10 Oct 2026 20:15:30 -0700 Subject: [PATCH 2/2] docs: move the contributing steps into a guide The readme's Contribute section was a bare npm script that no longer matched the repo. The steps now live in .github/contributing.md, which covers setup, the layout, tests and pull requests. The readme links to it. The "vscode ready" badge is gone; the guide mentions the VS Code settings instead. Co-Authored-By: Claude Opus 5.5 --- .github/contributing.md | 141 +++++++++++++++++++++++++++++++++-- packages/type-plus/readme.md | 4 - readme.md | 20 +---- 3 files changed, 138 insertions(+), 27 deletions(-) diff --git a/.github/contributing.md b/.github/contributing.md index 9592666cca..ccb19561c4 100644 --- a/.github/contributing.md +++ b/.github/contributing.md @@ -1,6 +1,137 @@ -# Contributing Guide +# Contributing to type-plus -## Icons +Thanks for taking the time to help. Every contribution counts, from a typo fix to a new type. + +This guide gets you from a fresh clone to a merged pull request. The full set of house rules lives in +[`AGENTS.md`](../AGENTS.md); you do not need to read it before your first change. + +## Ways to help + +- **Report a bug.** Open an [issue](https://github.com/cyberuni/type-plus/issues) with the smallest + code that shows it, and the TypeScript version you use. A + [TypeScript Playground](https://www.typescriptlang.org/play) link is the fastest way to show it. +- **Fix the docs.** Each page on the [website](https://cyberuni.github.io/type-plus/) has an + "Edit page" link at the bottom. +- **Fix a type or add one.** For a new type, open an issue first so we can agree on its name and + behavior before you write it. + +## Set up + +You need Node.js 24 and pnpm 12. If you use [mise](https://mise.jdx.dev), `mise install` gets both. +Otherwise, `corepack enable` gives you the pnpm version the repo pins. + +```sh +# after you fork the repo +git clone https://github.com//type-plus.git +cd type-plus +pnpm install +``` + +The repo ships VS Code settings and recommended extensions in `.vscode/`. VS Code offers to install the +extensions when you open the folder. + +## Find your way around + +| Path | What is there | +| ---------------------------- | ----------------------------------------------------------- | +| `packages/type-plus/src/` | The library. One file per type, with its spec beside it. | +| `apps/website/` | The documentation site (Astro and Starlight). | +| `.changeset/` | Release notes waiting for the next release. | + +`UnionKeys` shows the shape of every type in the library. `src/union-keys.ts` holds the type and its TSDoc: + +```ts +/** + * 🦴 *utilities* + * + * Gets the keys of every member of the union `T`. + * + * @example + * ```ts + * type R = UnionKeys<{ a: 1 } | { b: 2 }> // 'a' | 'b' + * ``` + */ +export type UnionKeys = keyof T | (T extends unknown ? keyof T : never) +``` + +`src/union-keys.spec.ts` checks it: + +```ts +import { it } from 'vitest' +import type { UnionKeys } from './index.js' +import { testType } from './testing/index.js' + +it('gets the keys of an object', () => { + testType.equal, 'a' | 'b'>(true) +}) +``` + +A type spec fails at compile time, not at run time: a wrong type is a compile error in the spec. + +## Make a change + +1. Create a branch: `git checkout -b fix-union-keys`. Do not start a branch name with `docs/`; + use `docs-` instead. +2. Run the tests in watch mode while you work: `pnpm tp watch`. +3. Write or change the type, and its spec next to it. +4. Document the type in TSDoc, with an `@example`. Add a `testType.equal` for the example to the + spec, so the example cannot drift from the type. +5. A new public type also needs a line in `packages/type-plus/src/index.ts`. + +A few naming rules that reviews catch most often: + +- Name a file in kebab-case after its main export: `find-last.ts` for `FindLast`. +- Title-case acronyms: `IsBigint` and `JsonTypes`, not `IsBigInt` or `JSONTypes`. +- Prefix internal helpers with `_` (`_union-to-intersection.ts`), and never export them from an entry. + +## Check your work + +```sh +pnpm verify +``` + +This is the same check CI runs. It compiles the type tests against TypeScript 5.4, 5.5, 5.6, 6.0 and 7, +because a type that works on one version can break on another. To run only the type tests: + +```sh +pnpm tp test:type +``` + +If you changed an error message that type-plus produces on purpose, update its snapshot and commit +the result: + +```sh +pnpm tp test:errors --update +``` + +To preview the documentation site, run `pnpm web dev`. + +## Open a pull request + +Commit messages follow [Conventional Commits](https://www.conventionalcommits.org). A git hook checks +each one, so a malformed message is rejected when you commit. + +```sh +git commit -m "fix(type-plus): keep optional keys in UnionKeys" +git commit -m "feat(type-plus): add FindLast" +git commit -m "docs(website): explain distributive types" +``` + +If your change affects the published package, add a changeset. It writes the release note: + +```sh +pnpm cs +``` + +Pick `type-plus`, choose the bump (`patch` for a fix, `minor` for a new type), and write one or two +sentences for users. Changes to the website or to tests only need no changeset. + +Then push your branch and open a pull request. CI runs `pnpm verify`, and a maintainer reviews it. +If something is unclear, ask in the pull request; questions are welcome. + +## Icons in TSDoc + +Each type's TSDoc starts with an icon that tells its category. - πŸ‘½ *alias* (:alien:): Alias of another type - 🚦 *assertion* (:vertical_traffic_light:): assertion function @@ -14,7 +145,7 @@ - 🧰 *type util* (:toolbox:): types for building types - 🦴 *utilities* (:bone:): provide various functionalities (other icons considered: πŸ”§πŸ”¨) -## πŸŒͺ️ *filter* +### πŸŒͺ️ *filter* `:tornado:` @@ -43,7 +174,7 @@ type R2 = Good // undefined (other icons considered: β†ͺοΈπŸ‘‰πŸš‹β©πŸΎπŸ”‘πŸšͺπŸ’‚πŸ§²πŸ™…β€β™‚οΈπŸͺš) -## 🎭 *predicate* +### 🎭 *predicate* `:performing_arts:` @@ -56,7 +187,7 @@ it returns `true` or `false` (other icons considered: β­•) -## πŸ”€ *distributive* +### πŸ”€ *distributive* `:twisted_rightwards_arrows:` diff --git a/packages/type-plus/readme.md b/packages/type-plus/readme.md index 6c34251479..568295e2e6 100644 --- a/packages/type-plus/readme.md +++ b/packages/type-plus/readme.md @@ -8,8 +8,6 @@ [![Release][github_release]][github_action_url] [![Codecov][codecov_image]][codecov_url] -[![Visual Studio Code][vscode_image]][vscode_url] - More than 200 type utilities for [TypeScript] for applications, library, and type-level programming. @@ -1426,6 +1424,4 @@ Whenever possible, I add attribution to the person who created those **codes** i [TypeScript]: https://www.typescriptlang.org [`typical`]: https://github.com/KiaraGrouwstra/typical [`utility-types`]: https://github.com/piotrwitek/utility-types -[vscode_image]: https://img.shields.io/badge/vscode-ready-green.svg -[vscode_url]: https://code.visualstudio.com/ [type_guard]: https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates diff --git a/readme.md b/readme.md index 260396c190..8f76a81098 100644 --- a/readme.md +++ b/readme.md @@ -8,8 +8,6 @@ [![Release][github_release]][github_action_url] [![Codecov][codecov_image]][codecov_url] -[![Visual Studio Code][vscode_image]][vscode_url] - More than 200 type utilities for [TypeScript] for applications, library, and type-level programming. [type-plus readme](./packages/type-plus/readme.md) @@ -29,20 +27,8 @@ See [What's new in 8.0](./packages/type-plus/readme.md#whats-new-in-80) for a su ## Contribute -```sh -# after fork and clone -npm install - -# begin making changes -git checkout -b -npm run watch - -# after making change(s) -git commit -m "" -git push - -# create PR -``` +Contributions are welcome, from typo fixes to new types. +The [contributing guide](./.github/contributing.md) walks you from a fresh clone to a pull request. [codecov_image]: https://codecov.io/gh/cyberuni/type-plus/branch/main/graph/badge.svg [codecov_url]: https://codecov.io/gh/cyberuni/type-plus @@ -52,5 +38,3 @@ git push [npm_image]: https://img.shields.io/npm/v/type-plus.svg?style=flat [npm_url]: https://npmjs.org/package/type-plus [TypeScript]: https://www.typescriptlang.org -[vscode_image]: https://img.shields.io/badge/vscode-ready-green.svg -[vscode_url]: https://code.visualstudio.com/