diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..b99bbae --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,71 @@ +name: Publish to npm + +on: + release: + types: [published] + +jobs: + # Build job + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: pnpm/action-setup@v3 + with: + version: 8 + + - uses: actions/setup-node@v4 + with: + node-version: '20' + + - name: Install dependencies + run: pnpm install + + - name: Build docs + run: pnpm run docs + + - name: Archive artifact + shell: sh + run: | + echo ::group::Archive artifact + tar \ + --dereference --hard-dereference \ + --directory "./docs" \ + -cvf "$RUNNER_TEMP/github-pages.tar" \ + --exclude=.git \ + --exclude=.github \ + . + echo ::endgroup:: + + - name: Upload artifact + id: upload-artifact + uses: actions/upload-artifact@v4 + with: + name: github-pages + path: ${{ runner.temp }}/github-pages.tar + if-no-files-found: error + + + # Deploy job + deploy: + # Add a dependency to the build job + needs: build + + # Grant GITHUB_TOKEN the permissions required to make a Pages deployment + permissions: + pages: write # to deploy to Pages + id-token: write # to verify the deployment originates from an appropriate source + + # Deploy to the github-pages environment + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + # Specify runner + deployment step + runs-on: ubuntu-latest + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 # or specific "vX.X.X" version tag for this action + diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 159cc1a..11fb431 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -5,7 +5,7 @@ on: types: [published] jobs: - build: + test-and-publish: runs-on: ubuntu-20.04 steps: - uses: actions/checkout@v4 diff --git a/.gitignore b/.gitignore index 37c3922..628ffe9 100644 --- a/.gitignore +++ b/.gitignore @@ -216,3 +216,5 @@ $RECYCLE.BIN/ *.lnk # End of https://www.toptal.com/developers/gitignore/api/node,macos,windows,linux + +docs/ diff --git a/package.json b/package.json index aac5479..cde10a7 100644 --- a/package.json +++ b/package.json @@ -18,11 +18,13 @@ "scripts": { "test": "vitest run", "prepublish": "tsup trycat.ts --dts --format cjs,esm", - "build": "tsup trycat.ts --dts --format cjs,esm" + "build": "tsup trycat.ts --dts --format cjs,esm", + "docs": "typedoc --out docs trycat.ts" }, "devDependencies": { "@biomejs/biome": "^1.7.1", "tsup": "^8.0.2", + "typedoc": "^0.25.13", "typescript": "^5.4.5", "vitest": "^1.5.2" } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 66d82dd..966e5f4 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -11,6 +11,9 @@ devDependencies: tsup: specifier: ^8.0.2 version: 8.0.2(typescript@5.4.5) + typedoc: + specifier: ^0.25.13 + version: 0.25.13(typescript@5.4.5) typescript: specifier: ^5.4.5 version: 5.4.5 @@ -795,6 +798,10 @@ packages: engines: {node: '>=12'} dev: true + /ansi-sequence-parser@1.1.1: + resolution: {integrity: sha512-vJXt3yiaUL4UU546s3rPXlsry/RnM730G1+HkpKE012AN0sx1eOrxSu95oKDIonskeLTijMgqWZ3uDEe3NFvyg==} + dev: true + /ansi-styles@4.3.0: resolution: {integrity: sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==} engines: {node: '>=8'} @@ -1235,6 +1242,10 @@ packages: resolution: {integrity: sha512-WriZw1luRMlmV3LGJaR6QOJjWwgLUTf89OwT2lUOyjX2dJGBwgmIkbcz+7WFZjrZM635JOIR517++e/67CP9dQ==} dev: true + /jsonc-parser@3.2.1: + resolution: {integrity: sha512-AilxAyFOAcK5wA1+LeaySVBrHsGQvUFCDWXKpZjzaL0PqW+xfBOttn8GNtWKFWqneyMZj41MWF9Kl6iPWLwgOA==} + dev: true + /lilconfig@3.1.1: resolution: {integrity: sha512-O18pf7nyvHTckunPWCV1XUNXU1piu01y2b7ATJ0ppkUkk8ocqVWBrYjJBCwHDjD/ZWcfyrA0P4gKhzWGi5EINQ==} engines: {node: '>=14'} @@ -1272,12 +1283,22 @@ packages: engines: {node: 14 || >=16.14} dev: true + /lunr@2.3.9: + resolution: {integrity: sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==} + dev: true + /magic-string@0.30.10: resolution: {integrity: sha512-iIRwTIf0QKV3UAnYK4PU8uiEc4SRh5jX0mwpIwETPpHdhVM4f53RSwS/vXvN1JhGX+Cs7B8qIq3d6AH49O5fAQ==} dependencies: '@jridgewell/sourcemap-codec': 1.4.15 dev: true + /marked@4.3.0: + resolution: {integrity: sha512-PRsaiG84bK+AMvxziE/lCFss8juXjNaWzVbN5tXAm4XjeaS9NAHhop+PjQxz2A9h8Q4M/xGmzP8vqNwy6JeK0A==} + engines: {node: '>= 12'} + hasBin: true + dev: true + /merge-stream@2.0.0: resolution: {integrity: sha512-abv/qOcuPfk3URPfDzmZU1LKmuw8kT+0nIHvKrKgFrwifol/doWcdA4ZqsWQ8ENrFKkd67Mfpo/LovbIUsbt3w==} dev: true @@ -1550,6 +1571,15 @@ packages: engines: {node: '>=8'} dev: true + /shiki@0.14.7: + resolution: {integrity: sha512-dNPAPrxSc87ua2sKJ3H5dQ/6ZaY8RNnaAqK+t0eG7p0Soi2ydiqbGOTaZCqaYvA/uZYfS1LJnemt3Q+mSfcPCg==} + dependencies: + ansi-sequence-parser: 1.1.1 + jsonc-parser: 3.2.1 + vscode-oniguruma: 1.7.0 + vscode-textmate: 8.0.0 + dev: true + /siginfo@2.0.0: resolution: {integrity: sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==} dev: true @@ -1743,6 +1773,20 @@ packages: engines: {node: '>=4'} dev: true + /typedoc@0.25.13(typescript@5.4.5): + resolution: {integrity: sha512-pQqiwiJ+Z4pigfOnnysObszLiU3mVLWAExSPf+Mu06G/qsc3wzbuM56SZQvONhHLncLUhYzOVkjFFpFfL5AzhQ==} + engines: {node: '>= 16'} + hasBin: true + peerDependencies: + typescript: 4.6.x || 4.7.x || 4.8.x || 4.9.x || 5.0.x || 5.1.x || 5.2.x || 5.3.x || 5.4.x + dependencies: + lunr: 2.3.9 + marked: 4.3.0 + minimatch: 9.0.4 + shiki: 0.14.7 + typescript: 5.4.5 + dev: true + /typescript@5.4.5: resolution: {integrity: sha512-vcI4UpRgg81oIRUFwR0WSIHKt11nJ7SAVlYNIu+QpqeyXP+gpQJy/Z4+F0aGxSE4MqwjyXvW/TzgkLAx2AGHwQ==} engines: {node: '>=14.17'} @@ -1864,6 +1908,14 @@ packages: - terser dev: true + /vscode-oniguruma@1.7.0: + resolution: {integrity: sha512-L9WMGRfrjOhgHSdOYgCt/yRMsXzLDJSL7BPrOZt73gU0iWO4mpqzqQzOz5srxqTvMBaR0XZTSrVWo4j55Rc6cA==} + dev: true + + /vscode-textmate@8.0.0: + resolution: {integrity: sha512-AFbieoL7a5LMqcnOF04ji+rpXadgOXnZsxQr//r83kLPr7biP7am3g9zbaZIaBGwBRWeSvoMD4mgPdX3e4NWBg==} + dev: true + /webidl-conversions@4.0.2: resolution: {integrity: sha512-YQ+BmxuTgd6UXZW3+ICGfyqRyHXVlD5GtQr5+qjiNW7bF0cqrzX500HVXPBOvgXb5YnzDd+h0zqyv61KUD7+Sg==} dev: true diff --git a/trycat.ts b/trycat.ts index 34e8eca..68ad44c 100644 --- a/trycat.ts +++ b/trycat.ts @@ -18,7 +18,7 @@ interface ResultBase { * Calls the provided function with the contained value if this Result is Ok. * Nothing is performed otherwise. * - * @param f The function to be called if this Result is Ok. First arg will receive the contained value. + * @param f - The function to be called if this Result is Ok. First arg will receive the contained value. * * @returns This Result. */ @@ -28,7 +28,7 @@ interface ResultBase { * Calls the provided function with the contained value if this Result is Err. * Nothing is performed otherwise. * - * @param f The function to be called if this Result is Err. First arg will receive the contained error. + * @param f - The function to be called if this Result is Err. First arg will receive the contained error. * * @returns This Result. */ @@ -38,7 +38,7 @@ interface ResultBase { * If this Result is Ok, calls the given mapper function with the current contained value * and returns a new Result containing the value returned by the mapper function. * - * @param mapper The function that maps the current contained value to another value. + * @param mapper - The function that maps the current contained value to another value. * * @returns A new Result object containing the value returned by the mapper function, or this if this is Err. */ @@ -48,8 +48,8 @@ interface ResultBase { * If this Result is Ok, it does the same thing as {@link map}. * Otherwise, returns the given default value. * - * @param def The default value to be returned if this Result is Err. - * @param mapper The function that maps the current contained value to another value if this Result is Ok. + * @param def - The default value to be returned if this Result is Err. + * @param mapper - The function that maps the current contained value to another value if this Result is Ok. * * @returns A new Result object containing the value returned by the mapped function if this is Ok, otherwise the default value. */ @@ -59,8 +59,8 @@ interface ResultBase { * Same as {@link mapOr}, except if this is Err, the default value is returned lazily by the first callback * which receives the contained error and returns the default value. * - * @param errMapper The function that maps the contained error value to a default value if this Result is Err. - * @param mapper The function that maps the contained value to a new value if this Result is Ok. + * @param errMapper - The function that maps the contained error value to a default value if this Result is Err. + * @param mapper - The function that maps the contained value to a new value if this Result is Ok. * * @returns The value returned by the error mapper if this is Err; The value returned by the value mapper if this is Ok. */ @@ -71,7 +71,7 @@ interface ResultBase { * then returns a new Result containing the new error value returned by the mapper. * Otherwise, nothing is performed and this is returned. * - * @param mapper The function that maps the contained error value to another error value. + * @param mapper - The function that maps the contained error value to another error value. * * @returns A new Result containing the error value returned by the mapper if this is Err, or this Result otherwise. */ @@ -122,7 +122,7 @@ interface ResultBase { /** * Returns the contained value if this Result is Ok, otherwise throws with the given error message. * - * @param The error message to be displayed if this Result is Err. + * @param message - The error message to be displayed if this Result is Err. * * @returns The contained value if this Result is Ok. * @throws An error with the given error message if this Result is Err. @@ -138,7 +138,7 @@ interface ResultBase { /** * Returns the contained error value if this Result is Err, otherwise throws with the given error message. * - * @param The error message to be displayed if this Result is Ok. + * @param message - The error message to be displayed if this Result is Ok. * * @returns The contained error value if this Result is Err. * @throws An error with the given error message if this Result is Ok. @@ -146,6 +146,13 @@ interface ResultBase { expectErr(message: string): TErr } +/** + * Stores the result of a successful operation. + * Access the contained via {@link Ok.value}. + * Refer to {@link ResultBase} for available methods. + * + * @see ResultBase + */ class Ok implements ResultBase { constructor(public readonly value: T) {} @@ -223,6 +230,13 @@ class Ok implements ResultBase { } } +/** + * Stores the error of a failed operation. + * Access the error via {@link Err.error}. + * Refer to {@link ResultBase} for available methods. + * + * @see ResultBase + */ class Err implements ResultBase { constructor(public readonly error: TErr) {} @@ -300,6 +314,14 @@ class Err implements ResultBase { } } +/** + * Represents the result of a fail-able operation. + * A successful operation returns {@link Ok}, and a failed operation returns {@link Err}. + * + * Refer to {@link ResultBase} for methods available on a {@link Result}. + * + * @see ResultBase + */ type Result = Ok | Err function ok(value: T): Ok { @@ -311,8 +333,8 @@ function err(error: TErr): Err { } /** - * Calls the given function, catches any thrown error into an Err, - * and wraps the returned value with an Ok if nothing goes wrong. + * Calls the given function, catches any thrown error into an {@link Err}, + * and wraps the returned value with an {@link Ok} if nothing goes wrong. */ function trys(fn: () => T): Result { try { @@ -324,7 +346,7 @@ function trys(fn: () => T): Result { /** * Stores the result of the given {@link Promise} into a {@link Result}. - * If the promise fails, Err is returned. If the promise succeeds, Ok is returned. + * If the promise fails, {@link Err} is returned. If the promise succeeds, {@link Ok} is returned. * * @example * const res = await tryp(fetch("/my/api")).mapErr((err) => apiError(err)) @@ -337,4 +359,4 @@ function tryp(promise: Promise): Promise> { } export { ok, err, trys, tryp } -export type { Result, Ok, Err } +export type { Result, ResultBase, Ok, Err }