diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index e9952f9..9c7a970 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -18,16 +18,19 @@ jobs: - name: Set up Deno uses: denoland/setup-deno@v1 with: - deno-version: 2.0.0 + deno-version: 2.0.2 - - name: Lint + - name: Lint code run: deno lint + - name: Lint docs + run: deno run lint-docs + - name: Format - run: deno fmt --check + run: deno run format-check - name: Test - run: deno test --coverage + run: deno run test-coverage - name: Generate Coverage run: deno coverage --lcov coverage/ > coverage.lcov diff --git a/.vscode/settings.json b/.vscode/settings.json index f81e060..4b46093 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -4,5 +4,11 @@ "source.organizeImports": "explicit" }, "editor.defaultFormatter": "denoland.vscode-deno", - "editor.formatOnSave": true + "editor.formatOnSave": true, + "[yaml]": { + "editor.insertSpaces": true, + "editor.tabSize": 4, + "editor.autoIndent": "advanced", + "diffEditor.ignoreTrimWhitespace": false + } } diff --git a/@coven/.DS_Store b/@coven/.DS_Store deleted file mode 100644 index 0d26a12..0000000 Binary files a/@coven/.DS_Store and /dev/null differ diff --git a/@coven/compare/CreateDifference.ts b/@coven/compare/CreateDifference.ts index 2e8e62e..91d87ea 100644 --- a/@coven/compare/CreateDifference.ts +++ b/@coven/compare/CreateDifference.ts @@ -6,7 +6,7 @@ import type { WithPropertyPath } from "./WithPropertyPath.ts"; * * @example Object that satisfies a creation difference * ```typescript - * const createDifference = ({ + * ({ * kind: "CREATE", * right: "created value", * path: ["property", "path"].values() diff --git a/@coven/compare/README.md b/@coven/compare/README.md index d7b0497..29162ed 100644 --- a/@coven/compare/README.md +++ b/@coven/compare/README.md @@ -3,7 +3,7 @@ [![JSR](https://jsr.io/badges/@coven/compare)](https://jsr.io/@coven/compare) [![JSR Score](https://jsr.io/badges/@coven/compare/score)](https://jsr.io/@coven/compare/score) -🪞 Minimalistic deep comparison. +⚖️ Minimalist diffing. This library takes 2 values (a `left` and a `right`) and returns an iterator with all the differences between said values. The differences are represented by diff --git a/@coven/compare/compare.ts b/@coven/compare/compare.ts index 4aaf076..3c07fd4 100644 --- a/@coven/compare/compare.ts +++ b/@coven/compare/compare.ts @@ -18,28 +18,15 @@ const alwaysFalse = always(false); * * @example Using compare with strings * ```typescript - * import { flat } from "@coven/compare"; - * import { assertEquals } from "@std/assert"; - * * const witchCompare = compare("🧙‍♀️"); - * - * assertEquals(flat(witchCompare("🧙‍♀️")), []); - * assertEquals( - * flat(witchCompare("🎃")), - * [{ kind: "UPDATE", left: "🧙‍♀️", right: "🎃", path: [] }] - * ); + * witchCompare("🧙‍♀️"); // Yields nothing + * witchCompare("🎃"); // Yields { kind: "UPDATE", left: "🧙‍♀️", right: "🎃", path: [] } * ``` * @example Using compare with objects * ```typescript - * import { flat } from "@coven/compare"; - * import { assertEquals } from "@std/assert"; - * * const witchObjectCompare = compare({ witch: "🧙‍♀️" }); * - * assertEquals( - * flat(witchObjectCompare({ witch: "🎃" })), - * [{ kind: "UPDATE", left: "🧙‍♀️", right: "🎃", path: ["witch"] }], - * ); + * witchObjectCompare({ witch: "🎃" }); // Yields { kind: "UPDATE", left: "🧙‍♀️", right: "🎃", path: ["witch"] } * ``` * @see {@linkcode CurriedComparison} * @see {@linkcode compareObjects} diff --git a/@coven/compare/compareIterables.ts b/@coven/compare/compareIterables.ts index ac1a175..de587ad 100644 --- a/@coven/compare/compareIterables.ts +++ b/@coven/compare/compareIterables.ts @@ -17,19 +17,10 @@ import { pathPrepend } from "./pathPrepend.ts"; * * @example Compare 2 arrays of numbers * ```typescript - * import { flat } from "@coven/compare"; - * import { assertEquals } from "@std/assert"; - * * const compare1342 = compareIterables([13, 42]); * - * assertEquals( - * flat(compare1342([13, 42])), - * [], - * ); - * assertEquals( - * flat(compare1342([13, 665])), - * [{ kind: "UPDATE", left: 42, right: 665, path: [1] }] - * ); + * compare1342([13, 42]); // Yields nothing + * compare1342([13, 665]); // Yields { kind: "UPDATE", left: 42, right: 665, path: [1] } * ``` * @see {@linkcode compare} * @param left Original iterable. diff --git a/@coven/compare/compareObjects.ts b/@coven/compare/compareObjects.ts index 67c4816..8f28cb8 100644 --- a/@coven/compare/compareObjects.ts +++ b/@coven/compare/compareObjects.ts @@ -14,14 +14,8 @@ import type { Difference } from "./Difference.ts"; * * @example Compare 2 objects with the same property but different value * ```typescript - * import { flat } from "@coven/compare"; - * import { assertEquals } from "@std/assert"; - * * const compareWitch = compareObjects({ witch: "🧙‍♀️" }); - * assertEquals( - * flat(compareWitch({ witch: "🎃" })), - * [{ kind: "UPDATE", left: "🧙‍♀️", right: "🎃", path: ["witch"] }] - * ); + * compareWitch({ witch: "🎃" }); // Yields { kind: "UPDATE", left: "🧙‍♀️", right: "🎃", path: ["witch"] } * ``` * @see {@linkcode compareIterables} * @see {@linkcode compareProperties} diff --git a/@coven/compare/compareProperties.ts b/@coven/compare/compareProperties.ts index eb8fab9..98e5fbd 100644 --- a/@coven/compare/compareProperties.ts +++ b/@coven/compare/compareProperties.ts @@ -13,15 +13,8 @@ import { pathPrepend } from "./pathPrepend.ts"; * * @example Compare objects * ```typescript - * import { flat } from "@coven/compare"; - * import { assertEquals } from "@std/assert"; - * * const compareWitch = compareProperties({ witch: "🧙‍♀️" }); - * - * assertEquals( - * flat(compareWitch({ witch: "🎃" })), - * [{ kind: "UPDATE", left: "🧙‍♀️", right: "🎃", path: ["witch"] }], - * ); + * compareWitch({ witch: "🎃" }); // Yields { kind: "UPDATE", left: "🧙‍♀️", right: "🎃", path: ["witch"] } * ``` * @see {@linkcode compare} * @see {@linkcode getKeys} diff --git a/@coven/compare/deno.json b/@coven/compare/deno.json index 7c5b786..6c013e0 100644 --- a/@coven/compare/deno.json +++ b/@coven/compare/deno.json @@ -1,5 +1,5 @@ { "name": "@coven/compare", - "version": "0.2.0", + "version": "0.3.0", "exports": "./mod.ts" } diff --git a/@coven/compare/differentiate.ts b/@coven/compare/differentiate.ts index a206423..3984faa 100644 --- a/@coven/compare/differentiate.ts +++ b/@coven/compare/differentiate.ts @@ -26,44 +26,26 @@ const differenceBase = { path: toIterable(EMPTY_ARRAY) }; * * @example Missing right value * ```typescript - * import { MISSING_VALUE, flat } from "@coven/compare"; - * import { assertEquals } from "@std/assert"; + * import { MISSING_VALUE } from "@coven/compare"; * - * assertEquals( - * flat(differentiate("🧙‍♀️")(MISSING_VALUE)), - * [{ kind: "DELETE", left: "🧙‍♀️", path: [] }] - * ); + * differentiate("🧙‍♀️")(MISSING_VALUE); // Yields { kind: "DELETE", left: "🧙‍♀️", path: [] } * ``` * @example Missing left value * ```typescript - * import { MISSING_VALUE, flat } from "@coven/compare"; - * import { assertEquals } from "@std/assert"; + * import { MISSING_VALUE } from "@coven/compare"; * - * assertEquals( - * flat(differentiate(MISSING_VALUE)("🎃")), - * [{ kind: "CREATE", right: "🎃", path: [] }] - * ); + * differentiate(MISSING_VALUE)("🎃"); // Yields { kind: "CREATE", right: "🎃", path: [] } * ``` * @example Both values set * ```typescript - * import { flat } from "@coven/compare"; - * import { assertEquals } from "@std/assert"; - * - * assertEquals( - * flat(differentiate("🧙‍♀️")("🎃")), - * [{ kind: "UPDATE", left: "🧙‍♀️", right: "🎃", path: [] }] - * ); - * differentiate("🧙‍♀️")("🧙‍♀️"); // yields [] + * differentiate("🧙‍♀️")("🎃"); // Yields { kind: "UPDATE", left: "🧙‍♀️", right: "🎃", path: [] } + * differentiate("🧙‍♀️")("🧙‍♀️"); // Yields nothing * ``` * @example Both values missing * ```typescript - * import { MISSING_VALUE, flat } from "@coven/compare"; - * import { assertEquals } from "@std/assert"; + * import { MISSING_VALUE } from "@coven/compare"; * - * assertEquals( - * flat(differentiate(MISSING_VALUE)(MISSING_VALUE)), - * [] - * ); + * differentiate(MISSING_VALUE)(MISSING_VALUE); // Yields nothing * ``` * @see {@linkcode Difference} * @param left Left/Original value. diff --git a/@coven/compare/flat.ts b/@coven/compare/flat.ts index 183b7c3..157fd23 100644 --- a/@coven/compare/flat.ts +++ b/@coven/compare/flat.ts @@ -10,17 +10,13 @@ import { flatPathMap } from "./flatPathMap.ts"; * @example Flatting a creation Difference * ```typescript * import type { Difference } from "@coven/compare"; - * import { assertEquals } from "@std/assert"; * - * assertEquals(flat([{ + * flat([{ * kind: "CREATE", * path: ["property", "path"].values(), * right: "created value", - * }].values() as Iterable), [{ - * kind: "CREATE", - * path: ["property", "path"], - * right: "created value", - * }]) + * }].values() as Iterable); + * // [{ kind: "CREATE", path: ["property", "path"], right: "created value" }] * ``` * @see {@linkcode Difference} * @see {@linkcode FlatDifference} diff --git a/@coven/compare/getKeys.ts b/@coven/compare/getKeys.ts index cfd3e0d..8f38645 100644 --- a/@coven/compare/getKeys.ts +++ b/@coven/compare/getKeys.ts @@ -9,9 +9,8 @@ const isFunctionConstructor = is(Function); * * @example Get keys of a plain object * ```typescript - * import { assertEquals } from "@std/assert"; - * - * assertEquals([...getKeys({})], []); + * getKeys({}); // Yields nothing + * getKeys({ coven: "engineering" }); // Yields "coven" * ``` * @param object Object to get the keys from. * @yields Object keys. diff --git a/@coven/compare/pathPrepend.ts b/@coven/compare/pathPrepend.ts index ce2001d..a8966f6 100644 --- a/@coven/compare/pathPrepend.ts +++ b/@coven/compare/pathPrepend.ts @@ -7,19 +7,11 @@ import { setPath } from "./setPath.ts"; * * @example Prepend string to path * ```typescript - * import { flat } from "@coven/compare"; - * import { assertEquals } from "@std/assert"; - * - * assertEquals(flat([ - * pathPrepend("coven")({ + * pathPrepend("coven")({ * kind: "DELETE", * left: 13, * path: ["engineering"].values() - * })]), [{ - * kind: "DELETE", - * left: 13, - * path: ["coven", "engineering"] - * }]); + * }); // Yields { kind: "DELETE", left: 13, path: ["coven", "engineering"] } * ``` * @param prepend Property to prepend. * @returns Curried generator with `prepend` in context. diff --git a/@coven/constants/EMPTY_ARRAY.ts b/@coven/constants/EMPTY_ARRAY.ts index d91c5c5..af97818 100644 --- a/@coven/constants/EMPTY_ARRAY.ts +++ b/@coven/constants/EMPTY_ARRAY.ts @@ -1,6 +1,9 @@ /** - * Empty read-only array. The array is read-only in runtime by `Object.freeze`, - * so trying to do mutations will throw. + * Empty read-only array. + * + * > [!IMPORTANT] + * > The array is read-only in runtime by `Object.freeze`, so trying to do + * > mutations will throw. * * @see [Object.freeze](https://mdn.io/Oject.freeze) */ diff --git a/@coven/constants/EMPTY_OBJECT.ts b/@coven/constants/EMPTY_OBJECT.ts index 603f37a..3f0ab06 100644 --- a/@coven/constants/EMPTY_OBJECT.ts +++ b/@coven/constants/EMPTY_OBJECT.ts @@ -1,6 +1,9 @@ /** - * Empty read-only `null` prototype object. The object is read-only in runtime - * by `Object.freeze`, so trying to do mutations will throw. + * Empty read-only `null` prototype object. + * + * > [!IMPORTANT] + * > The object is read-only in runtime by `Object.freeze`, so trying to do + * > mutations will throw. * * @see [Object.create](https://mdn.io/Object.create) * @see [Object.freeze](https://mdn.io/Object.freeze) diff --git a/@coven/constants/EMPTY_STRING.ts b/@coven/constants/EMPTY_STRING.ts index 7a6ab4f..7e24e53 100644 --- a/@coven/constants/EMPTY_STRING.ts +++ b/@coven/constants/EMPTY_STRING.ts @@ -1,4 +1,6 @@ /** - * Empty string. This one exists to have something more readable than `""`. + * Empty string. + * + * This one exists to have something more readable than `""`. */ export const EMPTY_STRING = ""; diff --git a/@coven/constants/README.md b/@coven/constants/README.md index 4118705..69056bd 100644 --- a/@coven/constants/README.md +++ b/@coven/constants/README.md @@ -3,16 +3,13 @@ [![JSR](https://jsr.io/badges/@coven/constants)](https://jsr.io/@coven/constants) [![JSR Score](https://jsr.io/badges/@coven/constants/score)](https://jsr.io/@coven/constants/score) -📖 Shared constants scrolls. +🧱 Common constants. ## Constants -- `EMPTY_ARRAY`: Empty read-only array. The array is read-only in runtime by - `Object.freeze`, so trying to do mutations will throw. -- `EMPTY_OBJECT`: Empty read-only `null` prototype object. The object is - read-only in runtime by `Object.freeze`, so trying to do mutations will throw. -- `EMPTY_STRING`: Empty string. This one exists to have something more readable - than `""`. +- `EMPTY_ARRAY`: Empty read-only array. +- `EMPTY_OBJECT`: Empty read-only `null` prototype object. +- `EMPTY_STRING`: Empty string. ## Example diff --git a/@coven/constants/deno.json b/@coven/constants/deno.json index 41e17d5..e738cf0 100644 --- a/@coven/constants/deno.json +++ b/@coven/constants/deno.json @@ -1,5 +1,5 @@ { "name": "@coven/constants", - "version": "0.1.0", + "version": "0.3.0", "exports": "./mod.ts" } diff --git a/@coven/cron/CronObject.ts b/@coven/cron/CronObject.ts index 16615aa..aaa3fcd 100644 --- a/@coven/cron/CronObject.ts +++ b/@coven/cron/CronObject.ts @@ -5,8 +5,8 @@ import type { MonthValue } from "./MonthValue.ts"; /** * Object that represents the 5 cron expression fields. * - * @see {@link Field} - * @see {@link MonthValue} + * @see {@linkcode Field} + * @see {@linkcode MonthValue} */ export type CronObject = { readonly dayOfMonth: Field; diff --git a/@coven/cron/Field.ts b/@coven/cron/Field.ts index e58c4d7..161d22b 100644 --- a/@coven/cron/Field.ts +++ b/@coven/cron/Field.ts @@ -3,12 +3,12 @@ import type { ListField } from "./ListField.ts"; import type { ValueOrRangeField } from "./ValueOrRangeField.ts"; /** - * Union of {@link AllToken}, {@link ValueOrRangeField} and {@link ListField} + * Union of {@linkcode AllToken}, {@linkcode ValueOrRangeField} and {@linkcode ListField} * that represents a field in a cron expression. * - * @see {@link AllToken} - * @see {@link ValueOrRangeField} - * @see {@link ListField} + * @see {@linkcode AllToken} + * @see {@linkcode ValueOrRangeField} + * @see {@linkcode ListField} */ export type Field = | AllToken diff --git a/@coven/cron/FieldString.ts b/@coven/cron/FieldString.ts index a3a1c7a..5040c3a 100644 --- a/@coven/cron/FieldString.ts +++ b/@coven/cron/FieldString.ts @@ -3,11 +3,11 @@ import type { ListString } from "./ListString.ts"; import type { ValueOrRangeString } from "./ValueOrRangeString.ts"; /** - * Union of {@link AllToken}, {@link ValueOrRangeString} and {@link ListString} + * Union of {@linkcode AllToken}, {@linkcode ValueOrRangeString} and {@linkcode ListString} * that represents a field in a cron expression. * - * @see {@link AllToken} - * @see {@link ValueOrRangeString} - * @see {@link ListString} + * @see {@linkcode AllToken} + * @see {@linkcode ValueOrRangeString} + * @see {@linkcode ListString} */ export type FieldString = AllToken | ListString | ValueOrRangeString; diff --git a/@coven/cron/ListField.ts b/@coven/cron/ListField.ts index e32ef82..2394fe7 100644 --- a/@coven/cron/ListField.ts +++ b/@coven/cron/ListField.ts @@ -4,7 +4,7 @@ import type { ValueOrRangeField } from "./ValueOrRangeField.ts"; /** * Type that represents a list of values for a cron object field. * - * @see {@link ValueOrRangeField} + * @see {@linkcode ValueOrRangeField} */ export type ListField = ReadonlyArray< ValueOrRangeField diff --git a/@coven/cron/ListString.ts b/@coven/cron/ListString.ts index 7d41baa..ab7666c 100644 --- a/@coven/cron/ListString.ts +++ b/@coven/cron/ListString.ts @@ -4,7 +4,7 @@ import type { ValueOrRangeString } from "./ValueOrRangeString.ts"; /** * Type that represents a list of values for a cron string field. * - * @see {@link ValueOrRangeString} + * @see {@linkcode ValueOrRangeString} */ export type ListString = `${string}${ListExpressionSeparatorToken}${ValueOrRangeString}`; diff --git a/@coven/cron/README.md b/@coven/cron/README.md index 6870f67..6e4c602 100644 --- a/@coven/cron/README.md +++ b/@coven/cron/README.md @@ -3,7 +3,7 @@ [![JSR](https://jsr.io/badges/@coven/cron)](https://jsr.io/@coven/cron) [![JSR Score](https://jsr.io/badges/@coven/cron/score)](https://jsr.io/@coven/cron/score) -⏳ A fantastic cron parser and constructor. +⏳ Fantastic cron parser and constructor. This library is the fastest, smallest and safest cron expression parser out there. This is because it uses a regular expression (built with @@ -30,8 +30,8 @@ import { parse, stringify } from "@coven/cron"; const cron = parse("1-2,3,4 * 2 8,9 1"); /* { - minutes: [{ from: 1, to: 2 }, 3, 4], - hours: "*", + minute: [{ from: 1, to: 2 }, 3, 4], + hour: "*", dayOfMonth: 2, month: [8, 9], dayOfWeek: 1 @@ -41,7 +41,7 @@ const cron = parse("1-2,3,4 * 2 8,9 1"); stringify(cron); // "1-2,3,4 * 2 8,9 1" // Also works with partials: -stringify({ hours: 13 }); // "* 13 * * *" +stringify({ hour: 13 }); // "* 13 * * *" // Only parses with valid dates: parse("* * 31 2 *"); // undefined because 31 of February is invalid diff --git a/@coven/cron/ValueOrRangeField.ts b/@coven/cron/ValueOrRangeField.ts index c66510e..009ec2c 100644 --- a/@coven/cron/ValueOrRangeField.ts +++ b/@coven/cron/ValueOrRangeField.ts @@ -1,7 +1,7 @@ import type { RangeField } from "./RangeField.ts"; /** - * Union of a set of numbers and a {@link RangeField} with that same set of + * Union of a set of numbers and a {@linkcode RangeField} with that same set of * numbers. */ export type ValueOrRangeField = RangeField | Value; diff --git a/@coven/cron/ValueOrRangeString.ts b/@coven/cron/ValueOrRangeString.ts index f51e19d..06e5460 100644 --- a/@coven/cron/ValueOrRangeString.ts +++ b/@coven/cron/ValueOrRangeString.ts @@ -1,6 +1,6 @@ import type { RangeString } from "./RangeString.ts"; /** - * Union of a set any number and a {@link RangeString}. + * Union of a set any number and a {@linkcode RangeString}. */ export type ValueOrRangeString = RangeString | `${number}`; diff --git a/@coven/cron/compareRangeOrValue.ts b/@coven/cron/compareRangeOrValue.ts index be9c666..1e57e4c 100644 --- a/@coven/cron/compareRangeOrValue.ts +++ b/@coven/cron/compareRangeOrValue.ts @@ -3,7 +3,7 @@ import { isRangeField } from "./isRangeField.ts"; import { FROM_NAME, TO_NAME } from "./rangeFieldNames.ts"; /** - * Compares `value` to a {@link ValueOrRangeField}. + * Compares `value` to a {@linkcode ValueOrRangeField}. * * @example * ```typescript @@ -13,7 +13,7 @@ import { FROM_NAME, TO_NAME } from "./rangeFieldNames.ts"; * compareRangeOrValue(13)(14); // false * ``` * @param value Value to be compared. - * @returns Curried function expecting a {@link ValueOrRangeField}. + * @returns Curried function expecting a {@linkcode ValueOrRangeField}. */ export const compareRangeOrValue = (value: number): (valueOrRange: ValueOrRangeField) => boolean => diff --git a/@coven/cron/deno.json b/@coven/cron/deno.json index 06f1096..a09209a 100644 --- a/@coven/cron/deno.json +++ b/@coven/cron/deno.json @@ -1,5 +1,5 @@ { "name": "@coven/cron", - "version": "0.1.0", + "version": "0.3.0", "exports": "./mod.ts" } diff --git a/@coven/cron/fieldRegExp.ts b/@coven/cron/fieldRegExp.ts index 375be87..a5ef7d4 100644 --- a/@coven/cron/fieldRegExp.ts +++ b/@coven/cron/fieldRegExp.ts @@ -7,7 +7,7 @@ import { valueRangeOrListRegExp } from "./valueRangeOrListRegExp.ts"; * * @example * ```typescript - * fieldRegExp("example", 13); // "(?\\*|(?:13(?:-13)?|(?:(?:13(?:-13)?,)+13(?:-13)?)))" + * fieldRegExp("example", "13"); // "(?\\*|(?:13(?:-13)?|(?:(?:13(?:-13)?,)+13(?:-13)?)))" * ``` * @param name Named group name. * @param value Possible values the expression can have. diff --git a/@coven/cron/isListField.ts b/@coven/cron/isListField.ts index 42b747e..069a57d 100644 --- a/@coven/cron/isListField.ts +++ b/@coven/cron/isListField.ts @@ -13,10 +13,10 @@ const everyIsNumberOrRangeField = every< ) => isNumber(item) || isRangeField(item)); /** - * Predicate checking if given value is a {@link ListField}. + * Predicate checking if given value is a {@linkcode ListField}. * - * @see {@link ListField} - * @see {@link isRangeField} + * @see {@linkcode ListField} + * @see {@linkcode isRangeField} */ export const isListField = (value: Field): value is ListField => isArray(value) && diff --git a/@coven/cron/isListString.ts b/@coven/cron/isListString.ts index 7a91f05..a059033 100644 --- a/@coven/cron/isListString.ts +++ b/@coven/cron/isListString.ts @@ -3,10 +3,10 @@ import type { ListString } from "./ListString.ts"; import { LIST_EXPRESSION_SEPARATOR_TOKEN } from "./tokens.ts"; /** - * Predicate checking if given value is a {@link ListString}. + * Predicate checking if given value is a {@linkcode ListString}. * - * @see {@link ListString} - * @see {@link LIST_EXPRESSION_SEPARATOR_TOKEN} + * @see {@linkcode ListString} + * @see {@linkcode LIST_EXPRESSION_SEPARATOR_TOKEN} */ export const isListString = includes( LIST_EXPRESSION_SEPARATOR_TOKEN, diff --git a/@coven/cron/isRangeField.ts b/@coven/cron/isRangeField.ts index cddb9ac..c2964dc 100644 --- a/@coven/cron/isRangeField.ts +++ b/@coven/cron/isRangeField.ts @@ -6,9 +6,9 @@ const hasFrom = has(FROM_NAME); const hasTo = has(TO_NAME); /** - * Predicate checking if given value is a cron object range ({@link RangeField}). + * Predicate checking if given value is a cron object range ({@linkcode RangeField}). * - * @see {@link RangeField} + * @see {@linkcode RangeField} */ export const isRangeField = (value: unknown): value is RangeField => isObject(value) && diff --git a/@coven/cron/isRangeString.ts b/@coven/cron/isRangeString.ts index 171395e..1a5a8f0 100644 --- a/@coven/cron/isRangeString.ts +++ b/@coven/cron/isRangeString.ts @@ -5,10 +5,10 @@ import { RANGE_EXPRESSION_SEPARATOR_TOKEN } from "./tokens.ts"; /** * Predicate checking if given value is a cron string range - * ({@link RangeString}). + * ({@linkcode RangeString}). * - * @see {@link RangeString} - * @see {@link rangeStringTest} + * @see {@linkcode RangeString} + * @see {@linkcode rangeStringTest} */ export const isRangeString = (value: string): value is RangeString => rangeStringTest(value) && diff --git a/@coven/cron/nextDates.ts b/@coven/cron/nextDates.ts index 122880e..61a2fc4 100644 --- a/@coven/cron/nextDates.ts +++ b/@coven/cron/nextDates.ts @@ -15,6 +15,8 @@ const dateReplace = join(quantity(2)(DIGIT), escape("."), quantity(3)(DIGIT)); * * @example * ```typescript + * import { take } from "@coven/iterables"; + * * take(2)(nextDates(new Date("1989-10-13T10:15:00.000Z"))("* * * * *")); * // [Date("1989-10-13T10:16:00.000"), Date("1989-10-13T10:17:00.000Z")] * ``` diff --git a/@coven/cron/parse.ts b/@coven/cron/parse.ts index a02484a..621ec40 100644 --- a/@coven/cron/parse.ts +++ b/@coven/cron/parse.ts @@ -19,10 +19,10 @@ const buildIU = build("iu"); * parse("* * 13 10 *"); // { minute: "*", hour: "*", dayOfMonth: 13, month: 10, dayOfWeek: "*" } * parse("5 * 10,11,13 1-10 *"); // { minute: 5, hour: "*", dayOfMonth: [10, 11, 13], month: { from: 1, to: 10 }, dayOfWeek: "*" } * parse("* * 31 2 *"); // undefined - * parse("nope"); // undefined + * parse("nope nope nope nope nope"); // undefined * ``` - * @see {@link parseFieldTuplesMap} - * @see {@link normalizeAliases} + * @see {@linkcode parseFieldTuplesMap} + * @see {@linkcode normalizeAliases} * * @param expression Cron expression to be parsed. * @returns Object representing that expression or `undefined` if expression is diff --git a/@coven/cron/parseField.ts b/@coven/cron/parseField.ts index 96b1a51..56c9a48 100644 --- a/@coven/cron/parseField.ts +++ b/@coven/cron/parseField.ts @@ -17,9 +17,9 @@ import type { RangeField } from "./RangeField.ts"; * parseField("10,11,13"); // [10, 11, 13] * parseField("1-10"); // { from: 1, to: 10 } * ``` - * @see {@link isAllToken} - * @see {@link parseList} - * @see {@link parseRange} + * @see {@linkcode isAllToken} + * @see {@linkcode parseList} + * @see {@linkcode parseRange} * * @param field Cron field value (should be validated before this). * @returns Parsed field. diff --git a/@coven/cron/parseFieldTuplesMap.ts b/@coven/cron/parseFieldTuplesMap.ts index 1f4592b..5cf0ee5 100644 --- a/@coven/cron/parseFieldTuplesMap.ts +++ b/@coven/cron/parseFieldTuplesMap.ts @@ -8,7 +8,7 @@ import type { RangeField } from "./RangeField.ts"; /** * Given an iterable of tuples with the name of a field and a field value, - * run each field through {@link parseField}. + * run each field through {@linkcode parseField}. * * @example * ```typescript @@ -17,7 +17,7 @@ import type { RangeField } from "./RangeField.ts"; * parseFieldTuplesMap([["minute", "10,11,13"]]); // [["minute", [10, 11, 13]]] * parseFieldTuplesMap([["minute", "1-10"]]); // [["minute", { from: 1, to: 10 }]] * ``` - * @see {@link parseField} + * @see {@linkcode parseField} */ export const parseFieldTuplesMap: ( fieldTuples: Iterable, diff --git a/@coven/cron/parseList.ts b/@coven/cron/parseList.ts index b199d98..53a8df3 100644 --- a/@coven/cron/parseList.ts +++ b/@coven/cron/parseList.ts @@ -12,7 +12,7 @@ import { LIST_EXPRESSION_SEPARATOR_TOKEN } from "./tokens.ts"; * ```typescript * parseList("10,11,13"); // [10, 11, 13] * ``` - * @see {@link isListString} + * @see {@linkcode isListString} * * @param value String that might be a list. * @returns Parsed list of `undefined` if it isn't a list string. diff --git a/@coven/cron/parseListMap.ts b/@coven/cron/parseListMap.ts index ce21fed..88007f9 100644 --- a/@coven/cron/parseListMap.ts +++ b/@coven/cron/parseListMap.ts @@ -12,8 +12,8 @@ import type { RangeField } from "./RangeField.ts"; * parseListMap(["1", "05", "13", "5-13", "13-13", "13-5", "99"]); * // [1, 5, 13, { from: 5, to: 13 }, 13, undefined, undefined] * ``` - * @see {@link parseNumber} - * @see {@link parseRange} + * @see {@linkcode parseNumber} + * @see {@linkcode parseRange} */ export const parseListMap: ( list: Iterable, diff --git a/@coven/cron/parseNumberMap.ts b/@coven/cron/parseNumberMap.ts index 5180e0f..e367b90 100644 --- a/@coven/cron/parseNumberMap.ts +++ b/@coven/cron/parseNumberMap.ts @@ -3,7 +3,7 @@ import type { Maybe } from "@coven/types"; import { parseNumber } from "./parseNumber.ts"; /** - * Maps given iterable through {@link parseNumber}. + * Maps given iterable through {@linkcode parseNumber}. * * @example * ```typescript @@ -12,7 +12,7 @@ import { parseNumber } from "./parseNumber.ts"; * parseNumberMap(["59"]); // [59] * parseNumberMap(["60"]); // [undefined] (60 isn't valid for any cron field) * ``` - * @see {@link parseNumber} + * @see {@linkcode parseNumber} */ export const parseNumberMap: ( iterable: Iterable, diff --git a/@coven/cron/parseNumberTest.ts b/@coven/cron/parseNumberTest.ts index 9f6efbc..adb17ea 100644 --- a/@coven/cron/parseNumberTest.ts +++ b/@coven/cron/parseNumberTest.ts @@ -24,7 +24,7 @@ import { paddedRegExp } from "./paddedRegExp.ts"; * parseNumberTest("foo"); // false * ``` * - * @see {@link paddedRegExp} + * @see {@linkcode paddedRegExp} */ export const parseNumberTest: (text: string) => boolean = test( buildUnicode( diff --git a/@coven/cron/parseRange.ts b/@coven/cron/parseRange.ts index a475f7f..a848dbc 100644 --- a/@coven/cron/parseRange.ts +++ b/@coven/cron/parseRange.ts @@ -16,9 +16,9 @@ import { zipRangeNames } from "./zipRangeNames.ts"; * parseRange("13-13"); // 13 (normalized) * parseRange("13-1"); // undefined * ``` - * @see {@link isRangeString} - * @see {@link zipRangeNames} - * @see {@link parseNumberMap} + * @see {@linkcode isRangeString} + * @see {@linkcode zipRangeNames} + * @see {@linkcode parseNumberMap} * * @param value String that might be a range. * @returns Parsed ranged of `undefined` if it isn't a range string. diff --git a/@coven/cron/stringify.ts b/@coven/cron/stringify.ts index 2758674..6825aff 100644 --- a/@coven/cron/stringify.ts +++ b/@coven/cron/stringify.ts @@ -21,9 +21,9 @@ import { ALL_TOKEN } from "./tokens.ts"; * }); // "5 * 10,11,13 1-10 *" * stringify({ month: 2, dayOfMonth: 31 }); // undefined * ``` - * @see {@link fieldNamesTuple} - * @see {@link stringifyField} - * @see {@link isValidExpression} + * @see {@linkcode fieldNamesTuple} + * @see {@linkcode stringifyField} + * @see {@linkcode isValidExpression} * * @param cron Cron object. * @returns Cron string expression. diff --git a/@coven/cron/stringifyField.ts b/@coven/cron/stringifyField.ts index 58b1980..9ec4a22 100644 --- a/@coven/cron/stringifyField.ts +++ b/@coven/cron/stringifyField.ts @@ -14,9 +14,9 @@ import { stringifyRange } from "./stringifyRange.ts"; * stringifyField([10, 11, 13]); // "10,11,13" * stringifyField({ from: 1, to: 10 }); // "1-10" * ``` - * @see {@link isAllToken} - * @see {@link stringifyList} - * @see {@link stringifyRange} + * @see {@linkcode isAllToken} + * @see {@linkcode stringifyList} + * @see {@linkcode stringifyRange} * * @param field Cron object field. * @returns Cron string field. diff --git a/@coven/cron/stringifyList.ts b/@coven/cron/stringifyList.ts index 086e105..c8db5d3 100644 --- a/@coven/cron/stringifyList.ts +++ b/@coven/cron/stringifyList.ts @@ -12,8 +12,8 @@ import { LIST_EXPRESSION_SEPARATOR_TOKEN } from "./tokens.ts"; * ```typescript * stringifyList([10, 11, 13]); // "10,11,13" * ``` - * @see {@link isListField} - * @see {@link stringifyRange} + * @see {@linkcode isListField} + * @see {@linkcode stringifyRange} * * @param field List cron object field * @returns String list or `undefined` if it isn't a list. diff --git a/@coven/cron/stringifyRange.ts b/@coven/cron/stringifyRange.ts index 6f6c9d5..2d14f95 100644 --- a/@coven/cron/stringifyRange.ts +++ b/@coven/cron/stringifyRange.ts @@ -10,9 +10,9 @@ import { RANGE_EXPRESSION_SEPARATOR_TOKEN } from "./tokens.ts"; * * @example * ```typescript - * parseRange({ from: 1, to: 13 }); // "1-13" + * stringifyRange({ from: 1, to: 13 }); // "1-13" * ``` - * @see {@link isRangeField} + * @see {@linkcode isRangeField} * * @param field Cron field to turn into a string. * @returns String ranged of `undefined` if it isn't a range object. diff --git a/@coven/expression/README.md b/@coven/expression/README.md index df79137..945729b 100644 --- a/@coven/expression/README.md +++ b/@coven/expression/README.md @@ -3,7 +3,7 @@ [![JSR](https://jsr.io/badges/@coven/expression)](https://jsr.io/@coven/expression) [![JSR Score](https://jsr.io/badges/@coven/expression/score)](https://jsr.io/@coven/expression/score) -🧙🏻‍♀️ Magically build regular expressions. +🧙‍♀️ Magical regular expressions composer. It is really easy to mess big regular expressions by forgetting some character. So, instead of using plain strings, `@coven/expression` provides a set of diff --git a/@coven/expression/build.ts b/@coven/expression/build.ts index cd3e7ee..4ef23fc 100644 --- a/@coven/expression/build.ts +++ b/@coven/expression/build.ts @@ -10,11 +10,13 @@ import { join } from "./join.ts"; /** * Builds a `RegExp` with required `u` flag and strongly typed source (using - * {@link join}). + * {@linkcode join}). * * @example * ```typescript - * build("ui")(group(or(13, "coven"))); // /(?:13|coven)/ui + * import { group, or } from "@coven/expression"; + * + * build("iu")(group(or(13, "coven"))); // /(?:13|coven)/iu * build()(group(or(13, "coven"))); // /(?:13|coven)/u -> use the buildUnicode alias * ``` * @template Flags Regular expression flags ("u" must be included always). diff --git a/@coven/expression/buildUnicode.ts b/@coven/expression/buildUnicode.ts index c247d53..20b9905 100644 --- a/@coven/expression/buildUnicode.ts +++ b/@coven/expression/buildUnicode.ts @@ -12,6 +12,8 @@ import { build } from "./build.ts"; * * @example * ```typescript + * import { group, or } from "@coven/expression"; + * * buildUnicode(group(or(13, "coven"))); // /(?:13|coven)/u * ``` * @param tokens String tokens to be used as the RegExp source. diff --git a/@coven/expression/deno.json b/@coven/expression/deno.json index d2d37e5..20032fc 100644 --- a/@coven/expression/deno.json +++ b/@coven/expression/deno.json @@ -1,5 +1,5 @@ { "name": "@coven/expression", - "version": "0.1.0", + "version": "0.3.0", "exports": "./mod.ts" } diff --git a/@coven/iterables/README.md b/@coven/iterables/README.md index fa62f29..52e5c60 100644 --- a/@coven/iterables/README.md +++ b/@coven/iterables/README.md @@ -3,7 +3,7 @@ [![JSR](https://jsr.io/badges/@coven/iterables)](https://jsr.io/@coven/iterables) [![JSR Score](https://jsr.io/badges/@coven/iterables/score)](https://jsr.io/@coven/iterables/score) -🌪️ Iteration rituals. +♻️ Iterable and AsyncIterable utilities. One of the places curried functions shine the most is with iterables. More often than not, mapping, filtering and so on is applied to multiple different @@ -24,8 +24,8 @@ While array operation has to go over all items before going to the next function, iterables run all functions in each item and yields them: ```typescript -const double = (value) => value * 2; -const next = (value) => value + 1; +const double = (value: number) => value * 2; +const next = (value: number) => value + 1; // With array methods @@ -39,6 +39,8 @@ const next = (value) => value + 1; // With iterables functions +import { forEach, map } from "@coven/iterables"; + // [1, 2, 3, 4] |> map(double) |> map(next) |> forEach(console.log); forEach(console.log)(map(next)(map(double)([1, 2, 3, 4]))); // 1. 2 → 3 → Logs 3 diff --git a/@coven/iterables/async/filter.ts b/@coven/iterables/async/filter.ts index 2fbff93..705dbfb 100644 --- a/@coven/iterables/async/filter.ts +++ b/@coven/iterables/async/filter.ts @@ -7,6 +7,8 @@ import { iteratorFunctionToAsyncIterableIterator } from "./iteratorFunctionToAsy * * @example * ```typescript + * import { iterableToArray } from "@coven/iterables/async"; + * * const filterEven = filter((number: number) => number % 2 === 0); * * iterableToArray(filterEven([1, 2, 3, 4])); // [2, 4] diff --git a/@coven/iterables/async/forEach.ts b/@coven/iterables/async/forEach.ts index 3850b60..0ea9a56 100644 --- a/@coven/iterables/async/forEach.ts +++ b/@coven/iterables/async/forEach.ts @@ -1,4 +1,4 @@ -import type { Awaitable, AwaitableIterable, Unary } from "@coven/types"; +import type { AwaitableEffect, AwaitableIterable } from "@coven/types"; /** * For each function for iterables and asynchronous iterables. @@ -9,14 +9,14 @@ import type { Awaitable, AwaitableIterable, Unary } from "@coven/types"; * * logEach([1, 2, 3]); // Logs 1, 2 and 3 separately * ``` - * @param callback Function to be called for every item of the iterable. + * @param awaitableEffect Function to be called for every item of the iterable. * @returns Curried function that expects an iterable to loop over and has `callback` set in context. */ export const forEach = ( - callback: Unary<[item: Item], Awaitable>, -): (iterable: AwaitableIterable) => Promise => + awaitableEffect: AwaitableEffect<[item: Item]>, +): AwaitableEffect<[iterable: AwaitableIterable]> => async (iterable: AwaitableIterable) => { for await (const item of iterable) { - await callback(item); + await awaitableEffect(item); } }; diff --git a/@coven/iterables/async/groupBy.ts b/@coven/iterables/async/groupBy.ts index 7498950..b6f9f2b 100644 --- a/@coven/iterables/async/groupBy.ts +++ b/@coven/iterables/async/groupBy.ts @@ -15,7 +15,7 @@ import { reduce } from "./reduce.ts"; * * @example * ```typescript - * const groupByType = groupBy((value: number) => number % 2 === 0 ? "even" : "odd"); + * const groupByType = groupBy((value: number) => value % 2 === 0 ? "even" : "odd"); * groupByType([1, 2, 3, 4, 5]); // { even: [2, 4], odd: [1, 3, 5] } * ``` * @param grouper Grouper function. diff --git a/@coven/iterables/async/iteratorFunctionToAsyncIterableIterator.ts b/@coven/iterables/async/iteratorFunctionToAsyncIterableIterator.ts index 6da4124..5eb7882 100644 --- a/@coven/iterables/async/iteratorFunctionToAsyncIterableIterator.ts +++ b/@coven/iterables/async/iteratorFunctionToAsyncIterableIterator.ts @@ -4,19 +4,17 @@ * * @example * ```typescript - * const identityGenerator = function* (value) { yield value; }; - * const iterableIterator = createIterableIterator(identityGenerator); + * const witchGenerator = function* () { yield "🧙🏻‍♀️"; }; + * const witchIterableIterator = iteratorFunctionToAsyncIterableIterator(witchGenerator); * - * const fooIdentity = iterableIterator("foo"); - * - * for (const value of fooIdentity) { - * console.log(value); // "foo" + * for await (const value of witchIterableIterator) { + * console.log(value); // "🧙🏻‍♀️" * } * - * // Same IterableIterator as above, return values again: + * // Same AsyncIterableIterator as above, return values again: * - * for (const value of fooIdentity) { - * console.log(value); // "foo" + * for await (const value of witchIterableIterator) { + * console.log(value); // "🧙🏻‍♀️" * } * ``` * @param iteratorFunction Generator to be used every time `Symbol.iterator` or `Symbol.asyncIterator` is called. diff --git a/@coven/iterables/async/map.ts b/@coven/iterables/async/map.ts index f8a34a2..290484d 100644 --- a/@coven/iterables/async/map.ts +++ b/@coven/iterables/async/map.ts @@ -6,7 +6,7 @@ import { iteratorFunctionToAsyncIterableIterator } from "./iteratorFunctionToAsy * * @example * ```typescript - * const double = value => value * 2; + * const double = (value: number) => value * 2; * const mapDouble = map(double); * * mapDouble([1, 2, 3]); // [2, 4, 6] diff --git a/@coven/iterables/async/mod.ts b/@coven/iterables/async/mod.ts index eb9292d..7b870c3 100644 --- a/@coven/iterables/async/mod.ts +++ b/@coven/iterables/async/mod.ts @@ -1,4 +1,8 @@ -/** @module Asynchronous */ +/** + * ♻️ Asynchronous iterable utilities. + * + * @module + */ export { append } from "./append.ts"; export { count } from "./count.ts"; export { drop } from "./drop.ts"; diff --git a/@coven/iterables/async/random.ts b/@coven/iterables/async/random.ts index 42bad26..cd24c8d 100644 --- a/@coven/iterables/async/random.ts +++ b/@coven/iterables/async/random.ts @@ -5,15 +5,17 @@ import { iteratorFunctionToAsyncIterableIterator } from "./iteratorFunctionToAsy * Deterministic pseudo-random number generator. * * > [!IMPORTANT] - * > This only works in secure contexts (HTTPS/Node). + * > This only works in secure contexts. * * @example * ```typescript + * import { iterableToArray, take } from "@coven/iterables/async"; + * * const seededRandom = random("some seed"); * const random0To10 = seededRandom(0)(10); * - * [...pick(2)(random0To10)]; // Two "random" values between 0 and 10 - * [...pick(2)(random0To10)]; // Same two "random" values between 0 and 10 + * iterableToArray(take(2)(random0To10)); // Two "random" values between 0 and 10 + * iterableToArray(take(2)(random0To10)); // Same two "random" values between 0 and 10 * ``` * @see [SubtleCrypto#digest](https://mdn.io/SubtleCrypto.digest) * @see [cryptoNumber](https://jsr.io/@coven/utils/doc/~/cryptoNumber) diff --git a/@coven/iterables/async/reduce.ts b/@coven/iterables/async/reduce.ts index 0580a2a..ee17589 100644 --- a/@coven/iterables/async/reduce.ts +++ b/@coven/iterables/async/reduce.ts @@ -6,7 +6,7 @@ import { forEach } from "./forEach.ts"; * * @example * ```typescript - * const sum = Accumulator(item => total => total + item); + * const sum = reduce(item => total => total + item); * const sumFrom0 = sum(0); * * sumFrom0([1, 2, 3]); // 6 diff --git a/@coven/iterables/async/toIterable.ts b/@coven/iterables/async/toIterable.ts index 981332f..18676f2 100644 --- a/@coven/iterables/async/toIterable.ts +++ b/@coven/iterables/async/toIterable.ts @@ -7,12 +7,14 @@ import { iteratorFunctionToAsyncIterableIterator } from "./iteratorFunctionToAsy * * @example * ```typescript + * import { getIterator } from "@coven/iterables/async" + * * const iterable = toIterable(1); * const iterator = getIterator(iterable); * iterator.next(); // { value: 1, done: false } * iterator.next(); // { value: undefined, done: true } * ``` - * @see {@link iteratorFunctionToAsyncIterableIterator} + * @see {@linkcode iteratorFunctionToAsyncIterableIterator} * * @template ValueOrIterable Generic of value or iterable to yield. * @param valueOrIterable Vale or iterable to yield. diff --git a/@coven/iterables/deno.json b/@coven/iterables/deno.json index f328ff1..99213cd 100644 --- a/@coven/iterables/deno.json +++ b/@coven/iterables/deno.json @@ -1,6 +1,6 @@ { "name": "@coven/iterables", - "version": "0.1.1", + "version": "0.3.0", "exports": { ".": "./mod.ts", "./async": "./async/mod.ts" diff --git a/@coven/iterables/filter.ts b/@coven/iterables/filter.ts index ad8ab2a..aa5a410 100644 --- a/@coven/iterables/filter.ts +++ b/@coven/iterables/filter.ts @@ -8,6 +8,8 @@ import { iteratorFunctionToIterableIterator } from "./iteratorFunctionToIterable * * @example * ```typescript + * import { iterableToArray } from "@coven/iterables"; + * * const filterEven = filter((number: number) => number % 2 === 0); * * iterableToArray(filterEven([1, 2, 3, 4])); // [2, 4] diff --git a/@coven/iterables/forEach.ts b/@coven/iterables/forEach.ts index da34610..46b5cba 100644 --- a/@coven/iterables/forEach.ts +++ b/@coven/iterables/forEach.ts @@ -1,4 +1,4 @@ -import type { Unary } from "@coven/types"; +import type { Effect } from "@coven/types"; import { getIterator } from "./getIterator.ts"; /** @@ -10,10 +10,10 @@ import { getIterator } from "./getIterator.ts"; * * logEach([1, 2, 3]); // Logs 1, 2 and 3 separately * ``` - * @param callback Function to be called for every item of the iterable. + * @param effect Function to be called for every item of the iterable. * @returns Curried function that expects an iterable to loop over and has `callback` set in context. */ export const forEach = ( - callback: Unary<[item: Item], void>, -): (iterable: Iterable) => void => -(iterable) => getIterator(iterable).forEach(callback); + effect: Effect<[item: Item]>, +): Effect<[iterable: Iterable]> => +(iterable) => getIterator(iterable).forEach(effect); diff --git a/@coven/iterables/groupBy.ts b/@coven/iterables/groupBy.ts index 95c093a..9f63da3 100644 --- a/@coven/iterables/groupBy.ts +++ b/@coven/iterables/groupBy.ts @@ -9,7 +9,7 @@ import { reduce } from "./reduce.ts"; * * @example * ```typescript - * const groupByType = groupBy((value: number) => number % 2 === 0 ? "even" : "odd"); + * const groupByType = groupBy((value: number) => value % 2 === 0 ? "even" : "odd"); * groupByType([1, 2, 3, 4, 5]); // { even: [2, 4], odd: [1, 3, 5] } * ``` * @param grouper Grouper function. diff --git a/@coven/iterables/iterableToIterableIterator.ts b/@coven/iterables/iterableToIterableIterator.ts deleted file mode 100644 index 0ed1831..0000000 --- a/@coven/iterables/iterableToIterableIterator.ts +++ /dev/null @@ -1,10 +0,0 @@ -export const iterableToIterableIterator = ( - iterable: Iterable, -): IterableIterator => { - const iterator = iterable[Symbol.iterator]; - - return { - ...iterator(), - [Symbol.iterator]: () => iterableToIterableIterator(iterable), - }; -}; diff --git a/@coven/iterables/iteratorFunctionToIterableIterator.ts b/@coven/iterables/iteratorFunctionToIterableIterator.ts index b955b07..25a70b6 100644 --- a/@coven/iterables/iteratorFunctionToIterableIterator.ts +++ b/@coven/iterables/iteratorFunctionToIterableIterator.ts @@ -3,18 +3,16 @@ * * @example * ```typescript - * const identityGenerator = function* (value) { yield value; }; - * const iterableIterator = createIterableIterator(identityGenerator); + * const witchGenerator = function* () { yield "🧙🏻‍♀️"; }; + * const witchIterableIterator = iteratorFunctionToIterableIterator(witchGenerator); * - * const fooIdentity = iterableIterator("foo"); - * - * for (const value of fooIdentity) { + * for (const value of witchIterableIterator) { * console.log(value); // "foo" * } * * // Same IterableIterator as above, return values again: * - * for (const value of fooIdentity) { + * for (const value of witchIterableIterator) { * console.log(value); // "foo" * } * ``` diff --git a/@coven/iterables/map.ts b/@coven/iterables/map.ts index c5f1d78..d65f82a 100644 --- a/@coven/iterables/map.ts +++ b/@coven/iterables/map.ts @@ -7,7 +7,7 @@ import { iteratorFunctionToIterableIterator } from "./iteratorFunctionToIterable * * @example * ```typescript - * const double = value => value * 2; + * const double = (value: number) => value * 2; * const mapDouble = map(double); * * mapDouble([1, 2, 3]); // [2, 4, 6] diff --git a/@coven/iterables/mod.ts b/@coven/iterables/mod.ts index 211eb6d..f58e285 100644 --- a/@coven/iterables/mod.ts +++ b/@coven/iterables/mod.ts @@ -1,4 +1,8 @@ -/** @module Synchronous */ +/** + * ♻️ Synchronous iterable utilities. + * + * @module + */ export { append } from "./append.ts"; export { count } from "./count.ts"; export { drop } from "./drop.ts"; diff --git a/@coven/iterables/objectToEntries.ts b/@coven/iterables/objectToEntries.ts index a26d7e2..260ff6c 100644 --- a/@coven/iterables/objectToEntries.ts +++ b/@coven/iterables/objectToEntries.ts @@ -6,7 +6,7 @@ import { iteratorFunctionToIterableIterator } from "./iteratorFunctionToIterable * * @example * ```typescript - * const entries = objectEntries({ a: 1, b: 2 }); + * const entries = objectToEntries({ a: 1, b: 2 }); * entries.next(); // { value: ["a", 1], done: false } * entries.next(); // { value: ["b", 2], done: false } * entries.next(); // { value: undefined, done: true } diff --git a/@coven/iterables/reduce.ts b/@coven/iterables/reduce.ts index 57f2113..106af10 100644 --- a/@coven/iterables/reduce.ts +++ b/@coven/iterables/reduce.ts @@ -6,7 +6,7 @@ import { getIterator } from "./getIterator.ts"; * * @example * ```typescript - * const sum = reduce(item => total => total + item); + * const sum = reduce(item => total => total + item); * const sumFrom0 = sum(0); * * sumFrom0([1, 2, 3]); // 6 diff --git a/@coven/iterables/toIterable.ts b/@coven/iterables/toIterable.ts index d792205..709a6df 100644 --- a/@coven/iterables/toIterable.ts +++ b/@coven/iterables/toIterable.ts @@ -7,12 +7,14 @@ import { iteratorFunctionToIterableIterator } from "./iteratorFunctionToIterable * * @example * ```typescript + * import { getIterator } from "@coven/iterables"; + * * const iterable = toIterable(1); * const iterator = getIterator(iterable); * iterator.next(); // { value: 1, done: false } * iterator.next(); // { value: undefined, done: true } * ``` - * @see {@link iteratorFunctionToIterableIterator} + * @see {@linkcode iteratorFunctionToIterableIterator} * * @template ValueOrIterable Generic of value or iterable to yield. * @param valueOrIterable Vale or iterable to yield. diff --git a/@coven/math/README.md b/@coven/math/README.md index 4b551d0..2953312 100644 --- a/@coven/math/README.md +++ b/@coven/math/README.md @@ -3,7 +3,7 @@ [![JSR](https://jsr.io/badges/@coven/math)](https://jsr.io/@coven/math) [![JSR Score](https://jsr.io/badges/@coven/math/score)](https://jsr.io/@coven/math/score) -💀 Math witchcraft. +🧮 Precise math utilities. Using this library, adding `0.2` + `0.1` will result in `0.3`, and that might look like nothing to the untrained eye, but it's not @@ -23,7 +23,7 @@ JavaScript runtimes. ```typescript import { calculate } from "@coven/math"; -calculate(0.1).add(0.2); // 0.3 🤯 +calculate(0.1).plus(0.2); // 0.3 🤯 ``` ## Other links diff --git a/@coven/math/add.ts b/@coven/math/add.ts index 3d6867b..8960511 100644 --- a/@coven/math/add.ts +++ b/@coven/math/add.ts @@ -2,7 +2,7 @@ import { pipe } from "./pipe.ts"; import { preciseAdd } from "./preciseAdd.ts"; /** - * Curried add operation using {@link pipe} with {@link preciseAdd}. + * Curried add operation using {@linkcode pipe} with {@linkcode preciseAdd}. * * @example * ```typescript @@ -10,8 +10,8 @@ import { preciseAdd } from "./preciseAdd.ts"; * * addDot2(0.1); // 0.3 * ``` - * @see {@link preciseAdd} - * @see {@link pipe} + * @see {@linkcode preciseAdd} + * @see {@linkcode pipe} * * @param augend Augend value to be on the right side. * @returns Curried function with `augend` in context. diff --git a/@coven/math/calculate.ts b/@coven/math/calculate.ts index 38e28cc..3563002 100644 --- a/@coven/math/calculate.ts +++ b/@coven/math/calculate.ts @@ -13,10 +13,10 @@ import { subtract } from "./subtract.ts"; * calculate(0.1).plus(0.2); // 0.3 * calculate(0.7).plus(0.3).dividedBy(4).times(2).minus(0.2); // 0.3 * ``` - * @see {@link add} - * @see {@link divide} - * @see {@link multiply} - * @see {@link subtract} + * @see {@linkcode add} + * @see {@linkcode divide} + * @see {@linkcode multiply} + * @see {@linkcode subtract} * @param value Value to run operations on. * @returns An object with `divideBy`, `minus`, `plus` and `times` methods and a `value` property. */ diff --git a/@coven/math/createPrecise.ts b/@coven/math/createPrecise.ts index 171a347..4c8431d 100644 --- a/@coven/math/createPrecise.ts +++ b/@coven/math/createPrecise.ts @@ -4,7 +4,7 @@ import type { MaybeInfinity } from "./MaybeInfinity.ts"; import type { Precise } from "./Precise.ts"; /** - * Takes a `base` and `exponent` and normalizes it returning a {@link Precise}. + * Takes a `base` and `exponent` and normalizes it returning a {@linkcode Precise}. * * @example * ```typescript @@ -12,10 +12,10 @@ import type { Precise } from "./Precise.ts"; * createPrecise(13n, -1n); // [13n, -1n] * createPrecise(1300n, 0n); // [13n, 2n] * ``` - * @see {@link Precise} - * @param base Base of the {@link Precise}. - * @param exponent Exponent of the {@link Precise}. - * @returns A normalized {@link Precise} value. + * @see {@linkcode Precise} + * @param base Base of the {@linkcode Precise}. + * @param exponent Exponent of the {@linkcode Precise}. + * @returns A normalized {@linkcode Precise} value. */ export const createPrecise: { (base: bigint, exponent?: bigint): Precise; diff --git a/@coven/math/deno.json b/@coven/math/deno.json index 3211c47..240f9a5 100644 --- a/@coven/math/deno.json +++ b/@coven/math/deno.json @@ -1,5 +1,5 @@ { "name": "@coven/math", - "version": "0.1.0", + "version": "0.3.0", "exports": "./mod.ts" } diff --git a/@coven/math/divide.ts b/@coven/math/divide.ts index 5a4d6d7..d97f113 100644 --- a/@coven/math/divide.ts +++ b/@coven/math/divide.ts @@ -2,7 +2,7 @@ import { pipe } from "./pipe.ts"; import { preciseDivide } from "./preciseDivide.ts"; /** - * Curried divide operation using {@link pipe} with {@link preciseDivide}. + * Curried divide operation using {@linkcode pipe} with {@linkcode preciseDivide}. * * @example * ```typescript @@ -10,8 +10,8 @@ import { preciseDivide } from "./preciseDivide.ts"; * * half(1); // 0.5 * ``` - * @see {@link preciseDivide} - * @see {@link pipe} + * @see {@linkcode preciseDivide} + * @see {@linkcode pipe} * @param divisor Divisor to be used in the division. * @returns Curried function with `divisor` in context. */ diff --git a/@coven/math/multiply.ts b/@coven/math/multiply.ts index 483bfe7..c371b7c 100644 --- a/@coven/math/multiply.ts +++ b/@coven/math/multiply.ts @@ -2,7 +2,7 @@ import { pipe } from "./pipe.ts"; import { preciseMultiply } from "./preciseMultiply.ts"; /** - * Curried multiply operation using {@link pipe} with {@link preciseMultiply}. + * Curried multiply operation using {@linkcode pipe} with {@linkcode preciseMultiply}. * * @example * ```typescript @@ -10,8 +10,8 @@ import { preciseMultiply } from "./preciseMultiply.ts"; * * double(6.5); // 13 * ``` - * @see {@link preciseMultiply} - * @see {@link pipe} + * @see {@linkcode preciseMultiply} + * @see {@linkcode pipe} * @param multiplier Multiplier value to be used in the multiplication. * @returns Curried function with `multiplier` in context. */ diff --git a/@coven/math/numberToPrecise.ts b/@coven/math/numberToPrecise.ts index 17788cd..6901134 100644 --- a/@coven/math/numberToPrecise.ts +++ b/@coven/math/numberToPrecise.ts @@ -3,7 +3,7 @@ import { createPrecise } from "./createPrecise.ts"; import type { Precise } from "./Precise.ts"; /** - * Turns a `number` into a {@link Precise}. + * Turns a `number` into a {@linkcode Precise}. * * @example * ```typescript @@ -11,9 +11,9 @@ import type { Precise } from "./Precise.ts"; * numberToPrecise(1.3); // [13n, -1n] * numberToPrecise(1300); // [13n, 2n] * ``` - * @see {@link createPrecise} + * @see {@linkcode createPrecise} * @param number Number to convert. - * @returns A {@link Precise} representation of the given `number`. + * @returns A {@linkcode Precise} representation of the given `number`. */ export const numberToPrecise = (number: number): Precise => { if (Number.isFinite(number)) { diff --git a/@coven/math/pipe.ts b/@coven/math/pipe.ts index 1825994..3424b39 100644 --- a/@coven/math/pipe.ts +++ b/@coven/math/pipe.ts @@ -3,18 +3,20 @@ import { numberToPrecise } from "./numberToPrecise.ts"; import { preciseToNumber } from "./preciseToNumber.ts"; /** - * Turns a {@link Precise} operation into a number operation. + * Turns a {@linkcode Precise} operation into a number operation. * * @example * ```typescript + * import { preciseAdd } from "@coven/math"; + * * const add = pipe(preciseAdd); * * add(0.1)(0.2); // 0.3 * ``` - * @see {@link numberToPrecise} - * @see {@link Precise} - * @see {@link preciseToNumber} - * @param preciseOperation {@link Precise} operation function. + * @see {@linkcode numberToPrecise} + * @see {@linkcode Precise} + * @see {@linkcode preciseToNumber} + * @param preciseOperation {@linkcode Precise} operation function. * @returns Number to number operation generated from `preciseOperation`. */ export const pipe = < diff --git a/@coven/math/preciseAdd.ts b/@coven/math/preciseAdd.ts index 671da99..6260ed0 100644 --- a/@coven/math/preciseAdd.ts +++ b/@coven/math/preciseAdd.ts @@ -5,7 +5,7 @@ import { createPrecise } from "./createPrecise.ts"; import { preciseToNumber } from "./preciseToNumber.ts"; /** - * Curried add operation using the internal {@link Precise} type. + * Curried add operation using the internal {@linkcode Precise} type. * * @example * ```typescript @@ -13,10 +13,10 @@ import { preciseToNumber } from "./preciseToNumber.ts"; * * addDot2(1n, -1n); // [3n, -1n] * ``` - * @see {@link bigIntMin} - * @see {@link createPrecise} - * @see {@link Precise} - * @see {@link preciseToNumber} + * @see {@linkcode bigIntMin} + * @see {@linkcode createPrecise} + * @see {@linkcode Precise} + * @see {@linkcode preciseToNumber} * @param augendBase Augend base to use in the right side of the addition. * @param augendExponent Augend exponent to use in the right side of the addition. * @returns Curried function with `augendBase` and `augendExponent` in context. diff --git a/@coven/math/preciseDivide.ts b/@coven/math/preciseDivide.ts index 9ab45e5..572d4e2 100644 --- a/@coven/math/preciseDivide.ts +++ b/@coven/math/preciseDivide.ts @@ -5,7 +5,7 @@ import { preciseMultiply } from "./preciseMultiply.ts"; import { preciseToNumber } from "./preciseToNumber.ts"; /** - * Curried divide operation using the internal {@link Precise} type. + * Curried divide operation using the internal {@linkcode Precise} type. * * @example * ```typescript @@ -13,10 +13,10 @@ import { preciseToNumber } from "./preciseToNumber.ts"; * * half(1n); // [5n, -1n] * ``` - * @see {@link numberToPrecise} - * @see {@link Precise} - * @see {@link preciseMultiply} - * @see {@link preciseToNumber} + * @see {@linkcode numberToPrecise} + * @see {@linkcode Precise} + * @see {@linkcode preciseMultiply} + * @see {@linkcode preciseToNumber} * @param divisorBase Divisor base to use in the division. * @param divisorExponent Divisor exponent to use in the division. * @returns Curried function with `divisorBase` and `divisorExponent` in context. diff --git a/@coven/math/preciseMultiply.ts b/@coven/math/preciseMultiply.ts index 124c1e7..87b96dc 100644 --- a/@coven/math/preciseMultiply.ts +++ b/@coven/math/preciseMultiply.ts @@ -4,7 +4,7 @@ import type { Precise } from "./Precise.ts"; import { createPrecise } from "./createPrecise.ts"; /** - * Curried multiply operation using the internal {@link Precise} type. + * Curried multiply operation using the internal {@linkcode Precise} type. * * @example * ```typescript @@ -12,8 +12,8 @@ import { createPrecise } from "./createPrecise.ts"; * * double(65n, -1n); // [13n] * ``` - * @see {@link createPrecise} - * @see {@link Precise} + * @see {@linkcode createPrecise} + * @see {@linkcode Precise} * @param multiplierBase Multiplier base to use in the multiplication. * @param multiplierExponent Multiplier exponent to use in the multiplication. * @returns Curried function with `multiplierBase` and `multiplierExponent` in context. diff --git a/@coven/math/preciseSubtract.ts b/@coven/math/preciseSubtract.ts index edd8445..0447e23 100644 --- a/@coven/math/preciseSubtract.ts +++ b/@coven/math/preciseSubtract.ts @@ -3,7 +3,7 @@ import type { Precise } from "./Precise.ts"; import { preciseAdd } from "./preciseAdd.ts"; /** - * Curried subtract operation using the internal {@link Precise} type. + * Curried subtract operation using the internal {@linkcode Precise} type. * * @example * ```typescript @@ -11,8 +11,8 @@ import { preciseAdd } from "./preciseAdd.ts"; * * previous(14n); // [13n] * ``` - * @see {@link Precise} - * @see {@link preciseAdd} + * @see {@linkcode Precise} + * @see {@linkcode preciseAdd} * @param subtrahendBase Subtrahend base to use in the subtraction. * @param subtrahendExponent Subtrahend exponent to use in the subtraction. * @returns Curried function with `subtrahendBase` and `subtrahendExponent` in context. diff --git a/@coven/math/subtract.ts b/@coven/math/subtract.ts index 407ccf7..d136578 100644 --- a/@coven/math/subtract.ts +++ b/@coven/math/subtract.ts @@ -2,7 +2,7 @@ import { pipe } from "./pipe.ts"; import { preciseSubtract } from "./preciseSubtract.ts"; /** - * Curried subtract operation using {@link pipe} with {@link preciseSubtract}. + * Curried subtract operation using {@linkcode pipe} with {@linkcode preciseSubtract}. * * @example * ```typescript @@ -10,8 +10,8 @@ import { preciseSubtract } from "./preciseSubtract.ts"; * * previous(14); // 13 * ``` - * @see {@link preciseSubtract} - * @see {@link pipe} + * @see {@linkcode preciseSubtract} + * @see {@linkcode pipe} * @param subtrahend Subtrahend value to be used in the subtraction. * @returns Curried function with `subtrahend` in context. */ diff --git a/@coven/pair/README.md b/@coven/pair/README.md index 814810d..cd440ed 100644 --- a/@coven/pair/README.md +++ b/@coven/pair/README.md @@ -3,7 +3,7 @@ [![JSR](https://jsr.io/badges/@coven/pair)](https://jsr.io/@coven/pair) [![JSR Score](https://jsr.io/badges/@coven/pair/score)](https://jsr.io/@coven/pair/score) -🧩 [Paired hook pattern](https://lou.cx/articles/the-paired-hook-pattern) +🖇️ [Paired hook pattern](https://lou.cx/articles/the-paired-hook-pattern) helper. ## Examples @@ -11,10 +11,11 @@ helper. ### Preact ```tsx -import { useState } from "preact"; +import { createElement } from "preact"; +import { useState } from "preact/hooks"; import { pair } from "@coven/pair/preact"; -const useCount = (initialCount) => { +const useCount = (initialCount: number) => { const [count, setCount] = useState(initialCount); return { onClick: () => setCount(count + 1), children: count }; @@ -44,10 +45,11 @@ const Component = ({ array = [] }) => ( ### React ```tsx -import { useState } from "react"; +// @deno-types="@types/react" +import { createElement, useState } from "react"; import { pair } from "@coven/pair/react"; -const useCount = (initialCount) => { +const useCount = (initialCount: number) => { const [count, setCount] = useState(initialCount); return { onClick: () => setCount(count + 1), children: count }; diff --git a/@coven/pair/deno.json b/@coven/pair/deno.json index 57cc99a..578d07d 100644 --- a/@coven/pair/deno.json +++ b/@coven/pair/deno.json @@ -1,6 +1,6 @@ { "name": "@coven/pair", - "version": "0.0.6", + "version": "0.3.0", "exports": { ".": "./mod.ts", "./preact": "./preact/mod.ts", diff --git a/@coven/pair/preact/PairedRenderFunction.ts b/@coven/pair/preact/PairedRenderFunction.ts index 7b465c2..e05a21c 100644 --- a/@coven/pair/preact/PairedRenderFunction.ts +++ b/@coven/pair/preact/PairedRenderFunction.ts @@ -1,12 +1,15 @@ import type { Unary } from "@coven/types"; -import type { h } from "preact"; +import type { Attributes, VNode } from "preact"; /** * Function that receives the paired hook and must return a `VNode`. * * @example * ```tsx - * const Example: PairedRenderFunction<() => number> = hook => <>{hook()}; + * import { createElement, Fragment } from "preact"; + * + * const Example: PairedRenderFunction<() => number> = hook => + * {hook()}; * ``` * @template Hook Hook function. */ @@ -14,5 +17,5 @@ export type PairedRenderFunction< Hook extends (...attributes: never) => unknown, > = Unary< [hook: Hook], - ReturnType + VNode >; diff --git a/@coven/pair/preact/mod.ts b/@coven/pair/preact/mod.ts index 0333e43..47f0255 100644 --- a/@coven/pair/preact/mod.ts +++ b/@coven/pair/preact/mod.ts @@ -1,4 +1,8 @@ -/** @module Preact */ +/** + * 🖇️ Preact [Paired hook pattern](https://lou.cx/articles/the-paired-hook-pattern) helper. + * + * @module + */ export { pair } from "./pair.ts"; export type { PairedComponentProperties } from "./PairedComponentProperties.ts"; export type { PairedRenderFunction } from "./PairedRenderFunction.ts"; diff --git a/@coven/pair/preact/pair.ts b/@coven/pair/preact/pair.ts index 1652d81..1d13a5a 100644 --- a/@coven/pair/preact/pair.ts +++ b/@coven/pair/preact/pair.ts @@ -6,7 +6,10 @@ import type { PairedComponentProperties } from "./PairedComponentProperties.ts"; * * @example * ```tsx - * const useCount = initialCount => { + * import { createElement } from "preact"; + * import { useState } from "preact/hooks"; + * + * const useCount = (initialCount: number) => { * const [count, setCount] = useState(initialCount); * * return { onClick: () => setCount(count + 1), children: count }; @@ -40,14 +43,8 @@ import type { PairedComponentProperties } from "./PairedComponentProperties.ts"; */ export const pair = unknown>( hook: Hook, -): FunctionComponent> => { - const PairedComponent = ((properties) => properties.children(hook)) as - & FunctionComponent< - PairedComponentProperties - > - & { displayName: string }; - - return ( - (PairedComponent.displayName = `paired(${hook.name})`), PairedComponent +): FunctionComponent> => + Object.assign( + ({ children }: PairedComponentProperties) => children(hook), + { displayName: `paired(${hook.name})` }, ); -}; diff --git a/@coven/pair/react/PairedRenderFunction.ts b/@coven/pair/react/PairedRenderFunction.ts index 7de816f..5dbddb2 100644 --- a/@coven/pair/react/PairedRenderFunction.ts +++ b/@coven/pair/react/PairedRenderFunction.ts @@ -1,12 +1,16 @@ import type { Unary } from "@coven/types"; -import type { createElement } from "react"; +// @deno-types="@types/react" +import type { ReactElement } from "react"; /** * Function that receives the paired hook and must return a `ReactElement`. * * @example * ```tsx - * const Example: PairedRenderFunction<() => number> = hook => <>{hook()}; + * import { createElement, Fragment } from "react"; + * + * const Example: PairedRenderFunction<() => number> = hook => + * {hook()}; * ``` * @template Hook Hook function. */ @@ -14,5 +18,5 @@ export type PairedRenderFunction< Hook extends (...attributes: never) => unknown, > = Unary< [hook: Hook], - ReturnType + ReactElement >; diff --git a/@coven/pair/react/mod.ts b/@coven/pair/react/mod.ts index 6bdc9d2..a606721 100644 --- a/@coven/pair/react/mod.ts +++ b/@coven/pair/react/mod.ts @@ -1,4 +1,8 @@ -/** @module React */ +/** + * 🖇️ React [Paired hook pattern](https://lou.cx/articles/the-paired-hook-pattern) helper. + * + * @module + */ export { pair } from "./pair.ts"; export type { PairedComponentProperties } from "./PairedComponentProperties.ts"; export type { PairedRenderFunction } from "./PairedRenderFunction.ts"; diff --git a/@coven/pair/react/pair.ts b/@coven/pair/react/pair.ts index 5ff520d..8d16034 100644 --- a/@coven/pair/react/pair.ts +++ b/@coven/pair/react/pair.ts @@ -1,3 +1,4 @@ +// @deno-types="@types/react" import type { FunctionComponent } from "react"; import { pair as preactPair } from "../preact/pair.ts"; import type { PairedComponentProperties } from "./PairedComponentProperties.ts"; @@ -7,7 +8,9 @@ import type { PairedComponentProperties } from "./PairedComponentProperties.ts"; * * @example * ```tsx - * const useCount = initialCount => { + * import { createElement, useState } from "react"; + * + * const useCount = (initialCount: number) => { * const [count, setCount] = useState(initialCount); * * return { onClick: () => setCount(count + 1), children: count }; diff --git a/@coven/parsers/README.md b/@coven/parsers/README.md index 88b799d..7cd5b86 100644 --- a/@coven/parsers/README.md +++ b/@coven/parsers/README.md @@ -3,7 +3,7 @@ [![JSR](https://jsr.io/badges/@coven/parsers)](https://jsr.io/@coven/parsers) [![JSR Score](https://jsr.io/badges/@coven/parsers/score)](https://jsr.io/@coven/parsers/score) -💫 Parsing charms. +💫 Parsing utilities. Instead of throwing or returning values like `NaN`, the parsers in this library either return the expected parsed value or `undefined` (making use of the diff --git a/@coven/parsers/attempt.ts b/@coven/parsers/attempt.ts index d8df2fd..8360398 100644 --- a/@coven/parsers/attempt.ts +++ b/@coven/parsers/attempt.ts @@ -1,8 +1,10 @@ import type { Just, Maybe, ReadonlyArray } from "@coven/types"; /** - * This functions tries to run a function and silences the `throw`s by wrapping - * it with a `try/catch` and returning `undefined` instead. + * Attempts to run a function and silences throws. + * + * It silences the `throw`s by wrapping it with a `try/catch` and returning + * `undefined` instead. * * @example * ```typescript diff --git a/@coven/parsers/clone.ts b/@coven/parsers/clone.ts index 545362d..043cea6 100644 --- a/@coven/parsers/clone.ts +++ b/@coven/parsers/clone.ts @@ -2,6 +2,8 @@ import type { Maybe, StructuredData } from "@coven/types"; import { attempt } from "./attempt.ts"; /** + * `structuredClone` wrapped in {@linkcode attempt}. + * * This util makes use of `structuredClone` to clone the given value, but * instead of throwing a `DOMException`, it simply returns `undefined` when * the value is not serializable. @@ -9,9 +11,9 @@ import { attempt } from "./attempt.ts"; * @example * ```typescript * clone({ foo: "bar" }); // { foo: "bar" } - * clone({ function: () => {} }); // undefined + * clone({ function: (() => {}) as unknown as string }); // undefined * ``` - * @see {@link attempt} + * @see {@linkcode attempt} * @see [structuredClone](https://mdn.io/structuredClone) * @template Type Type of the value to be cloned. * @param value Value to be cloned. diff --git a/@coven/parsers/deno.json b/@coven/parsers/deno.json index 2d5fd66..6832e88 100644 --- a/@coven/parsers/deno.json +++ b/@coven/parsers/deno.json @@ -1,5 +1,5 @@ { "name": "@coven/parsers", - "version": "0.0.8", + "version": "0.3.0", "exports": "./mod.ts" } diff --git a/@coven/parsers/omitProtoReviver.ts b/@coven/parsers/omitProtoReviver.ts index 7296946..7facf78 100644 --- a/@coven/parsers/omitProtoReviver.ts +++ b/@coven/parsers/omitProtoReviver.ts @@ -1,11 +1,13 @@ /** + * Reviver that skips `__proto__`. + * * JSON parsing has a proto poisoning vulnerability that can be exploited by * passing a JSON string with a `__proto__` key. This reviver can be used to * prevent that. * * @example * ```typescript - * JSON.parse('{"__proto__":"😈"}', omitProto); // {} + * JSON.parse('{"__proto__":"😈"}', omitProtoReviver); // {} * ``` * @param key Current key. * @param value Current value. diff --git a/@coven/parsers/parseBinary.ts b/@coven/parsers/parseBinary.ts index f950e01..e66a7f5 100644 --- a/@coven/parsers/parseBinary.ts +++ b/@coven/parsers/parseBinary.ts @@ -2,6 +2,8 @@ import type { NumberParser } from "./NumberParser.ts"; import { parseInteger } from "./parseInteger.ts"; /** + * String to binary parser. + * * Parses a `string` to a binary `number`, returning `undefined` instead of * `NaN` if it fails. * @@ -11,7 +13,7 @@ import { parseInteger } from "./parseInteger.ts"; * parseBinary("101.5"); // 0b101 -> 5 * parseBinary("invalid"); // undefined * ``` - * @see {@link parseInteger} + * @see {@linkcode parseInteger} * @param string String to be parsed. * @returns Parsed `number` or `undefined` if it fails. */ diff --git a/@coven/parsers/parseDecimal.ts b/@coven/parsers/parseDecimal.ts index 092510b..179bce3 100644 --- a/@coven/parsers/parseDecimal.ts +++ b/@coven/parsers/parseDecimal.ts @@ -2,6 +2,8 @@ import type { NumberParser } from "./NumberParser.ts"; import { parseInteger } from "./parseInteger.ts"; /** + * String to decimal parser. + * * Parses a `string` to a decimal `number`, returning `undefined` instead of * `NaN` if it fails. * @@ -11,7 +13,7 @@ import { parseInteger } from "./parseInteger.ts"; * parseDecimal("101.5"); // 101 * parseDecimal("invalid"); // undefined * ``` - * @see {@link parseInteger} + * @see {@linkcode parseInteger} * @param string String to be parsed. * @returns Parsed `number` or `undefined` if it fails. */ diff --git a/@coven/parsers/parseFloatingPoint.ts b/@coven/parsers/parseFloatingPoint.ts index 639edb4..d251e78 100644 --- a/@coven/parsers/parseFloatingPoint.ts +++ b/@coven/parsers/parseFloatingPoint.ts @@ -2,16 +2,18 @@ import type { Maybe } from "@coven/types"; import { undefineNaN } from "./undefineNaN.ts"; /** + * String to float parser. + * * Parses a `string` to a float `number`. Returns `undefined` instead of `NaN` * if it fails. * * @example * ```typescript - * parseFloatingPoint(10); // 10 - * parseFloatingPoint(13.10); // 13.1 + * parseFloatingPoint("10"); // 10 + * parseFloatingPoint("13.10"); // 13.1 * parseFloatingPoint("invalid"); // undefined * ``` - * @see {@link undefineNaN} + * @see {@linkcode undefineNaN} * @param string String to parse. * @returns Parsed number or `undefined` if invalid. */ diff --git a/@coven/parsers/parseHexadecimal.ts b/@coven/parsers/parseHexadecimal.ts index 398e2e3..1513fe9 100644 --- a/@coven/parsers/parseHexadecimal.ts +++ b/@coven/parsers/parseHexadecimal.ts @@ -2,6 +2,8 @@ import type { NumberParser } from "./NumberParser.ts"; import { parseInteger } from "./parseInteger.ts"; /** + * String to hexadecimal parser. + * * Parses a `string` to a hexadecimal `number`, returning `undefined` instead of * `NaN` if it fails. * @@ -11,7 +13,7 @@ import { parseInteger } from "./parseInteger.ts"; * parseHexadecimal("101.5"); // 0x101 -> 257 * parseHexadecimal("invalid"); // undefined * ``` - * @see {@link parseInteger} + * @see {@linkcode parseInteger} * @param string String to be parsed. * @returns Parsed `number` or `undefined` if it fails. */ diff --git a/@coven/parsers/parseInteger.ts b/@coven/parsers/parseInteger.ts index 5dc5a31..6fd2c81 100644 --- a/@coven/parsers/parseInteger.ts +++ b/@coven/parsers/parseInteger.ts @@ -3,6 +3,8 @@ import type { NumberParser } from "./NumberParser.ts"; import { undefineNaN } from "./undefineNaN.ts"; /** + * String to integer parser. + * * Parses a `string` to a `number` with the given `radix`, returning `undefined` * instead of `NaN` if it fails. * @@ -14,7 +16,7 @@ import { undefineNaN } from "./undefineNaN.ts"; * parseDecimal("101.5"); // 101 * parseDecimal("invalid"); // undefined * ``` - * @see {@link undefineNaN} + * @see {@linkcode undefineNaN} * @param radix Radix to use for parsing (`16` for hexadecimal, `10` for decimal, and so on). * @returns Curried function with `radix` in context. */ @@ -22,8 +24,8 @@ export const parseInteger = (radix: Radix): NumberParser => /** * Curried function with `radix` set. * - * @see {@link undefineNaN} - * @see {@link parseInteger} + * @see {@linkcode undefineNaN} + * @see {@linkcode parseInteger} * @param string String to parse. * @returns Parsed `number` or `undefined` if it fails. */ diff --git a/@coven/parsers/parseJSON.ts b/@coven/parsers/parseJSON.ts index 18a9613..63a0760 100644 --- a/@coven/parsers/parseJSON.ts +++ b/@coven/parsers/parseJSON.ts @@ -3,7 +3,10 @@ import { attempt } from "./attempt.ts"; import { omitProtoReviver } from "./omitProtoReviver.ts"; /** - * `JSON.parse` is unsafe by default, allowing __proto__ poisoning. This + * `JSON.parse` wrapped in {@linkcode attempt} and using + * {@linkcode omitProtoReviver}. + * + * `JSON.parse` is unsafe by default, allowing `__proto__` poisoning. This * function takes care of it while making its types safer as well. * * @example @@ -11,8 +14,8 @@ import { omitProtoReviver } from "./omitProtoReviver.ts"; * parseJSON('{"__proto__":"😈"}'); // {} * parseJSON("invalid"); // undefined * ``` - * @see {@link attempt} - * @see {@link omitProtoReviver} + * @see {@linkcode attempt} + * @see {@linkcode omitProtoReviver} * @template Output Generic of the output (has to be a `JSONValue`). * @param string String to be parsed. * @returns Parsed string or `undefined` if invalid JSON. diff --git a/@coven/parsers/parseOctal.ts b/@coven/parsers/parseOctal.ts index dac7905..e81e450 100644 --- a/@coven/parsers/parseOctal.ts +++ b/@coven/parsers/parseOctal.ts @@ -2,6 +2,8 @@ import type { NumberParser } from "./NumberParser.ts"; import { parseInteger } from "./parseInteger.ts"; /** + * String to octal parser. + * * Parses a `string` to a octal `number`, returning `undefined` instead of `NaN` * if it fails. * @@ -11,7 +13,7 @@ import { parseInteger } from "./parseInteger.ts"; * parseOctal("101.5"); // 0o101 -> 65 * parseOctal("invalid"); // undefined * ``` - * @see {@link parseInteger} + * @see {@linkcode parseInteger} * @param string String to be parsed. * @returns Parsed `number` or `undefined` if it fails. */ diff --git a/@coven/parsers/undefineNaN.ts b/@coven/parsers/undefineNaN.ts index 44fb508..85534b9 100644 --- a/@coven/parsers/undefineNaN.ts +++ b/@coven/parsers/undefineNaN.ts @@ -1,6 +1,8 @@ import type { Maybe } from "@coven/types"; /** + * Turns `NaN` into `undefined`. + * * Takes a `number` that could be `NaN` and makes it `undefined` if it is `NaN`. * * @example diff --git a/@coven/predicates/IsInstanceOfFunction.ts b/@coven/predicates/IsInstanceOfFunction.ts index fc0c204..ea7c0e7 100644 --- a/@coven/predicates/IsInstanceOfFunction.ts +++ b/@coven/predicates/IsInstanceOfFunction.ts @@ -1,8 +1,7 @@ import type { Class } from "@coven/types"; /** - * Function that checks if a given `input` is an `instanceof` the given - * {@link Class}. + * Function that checks if a given `input` is an `instanceof` the given class. * * @template Expected Expected class type. */ diff --git a/@coven/predicates/IsTypeFunction.ts b/@coven/predicates/IsTypeFunction.ts index 914ce57..61216bc 100644 --- a/@coven/predicates/IsTypeFunction.ts +++ b/@coven/predicates/IsTypeFunction.ts @@ -1,9 +1,9 @@ import type { TypeOfDictionary } from "@coven/types"; /** - * Function that maps the given `input` value to a type of - * {@link TypeOfDictionary}. + * Function that maps the given `input` value to a type of `TypeOfDictionary`. * + * @see [TypeOfDictionary](https://jsr.io/@coven/types/doc/~/TypeOfDictionary) * @template Type Key of `TypeOfDictionary`. */ export type IsTypeFunction = ( diff --git a/@coven/predicates/README.md b/@coven/predicates/README.md index b1dcf45..a7923c7 100644 --- a/@coven/predicates/README.md +++ b/@coven/predicates/README.md @@ -3,7 +3,7 @@ [![JSR](https://jsr.io/badges/@coven/predicates)](https://jsr.io/@coven/predicates) [![JSR Score](https://jsr.io/badges/@coven/predicates/score)](https://jsr.io/@coven/predicates/score) -🛡️ Predicate wards. +🕵️‍♀️ Predicate utilities. This library offers a collection of common predicate functions to check for type, instances, presence of properties and more. diff --git a/@coven/predicates/between.ts b/@coven/predicates/between.ts index 100c72d..e1f5d5f 100644 --- a/@coven/predicates/between.ts +++ b/@coven/predicates/between.ts @@ -1,7 +1,7 @@ import type { Numeric } from "@coven/types"; /** - * Takes a `start` and `end` and returns a boolean if `value` number or string is between them. + * Checks if a `value` is between `start` and `end`. * * @example * ```typescript diff --git a/@coven/predicates/deno.json b/@coven/predicates/deno.json index 4c5083a..34719f1 100644 --- a/@coven/predicates/deno.json +++ b/@coven/predicates/deno.json @@ -1,5 +1,5 @@ { "name": "@coven/predicates", - "version": "0.1.0", + "version": "0.3.0", "exports": "./mod.ts" } diff --git a/@coven/predicates/has.ts b/@coven/predicates/has.ts index 62bfcd3..820c47a 100644 --- a/@coven/predicates/has.ts +++ b/@coven/predicates/has.ts @@ -2,9 +2,7 @@ import type { ReadonlyRecord } from "@coven/types"; import type { HasFunction } from "./HasFunction.ts"; /** - * Curried wrapper for the `in` operator. Given a `property` name and an - * `object`, returns `true` the object contains that property, `false` - * otherwise. + * Checks given property is `in` given object. * * @example * ```typescript diff --git a/@coven/predicates/hasPrototype.ts b/@coven/predicates/hasPrototype.ts index 5f57457..6e76088 100644 --- a/@coven/predicates/hasPrototype.ts +++ b/@coven/predicates/hasPrototype.ts @@ -9,11 +9,11 @@ const hasPrototypeProperty = has("prototype"); * * @example * ```typescript - * hasIteratorSymbol({ [Symbol.iterator]() {} }); // true - * hasIteratorSymbol({ bar: "bar" }); // false + * hasPrototype(Array); // true + * hasPrototype([]); // false * ``` - * @returns `true` when given object has the `Symbol.iterator` symbol, `false` - * otherwise. + * @returns `true` when given object has a `prototype` property and it is an + * object, `false` otherwise. */ export const hasPrototype = ( object: object, diff --git a/@coven/predicates/is.ts b/@coven/predicates/is.ts index e8e21e6..2838f53 100644 --- a/@coven/predicates/is.ts +++ b/@coven/predicates/is.ts @@ -1,6 +1,5 @@ /** - * Curried wrapper for `Object.is`. Given and `expected` value and an `actual` - * value, returns `true` if those values are equal, or `false` if not. + * Curried wrapper for `Object.is`. * * @example * ```typescript @@ -9,6 +8,7 @@ * is2(2); // true * is2(8); // false * ``` + * @see [Object.is](https://mdn.io/Object.is) * @returns Curried function with `expected` in context. */ export const is = ( diff --git a/@coven/predicates/isAsyncIterable.ts b/@coven/predicates/isAsyncIterable.ts index 3607d12..13d2a0b 100644 --- a/@coven/predicates/isAsyncIterable.ts +++ b/@coven/predicates/isAsyncIterable.ts @@ -5,8 +5,9 @@ import { isObject } from "./isObject.ts"; /** * Check if given value is `AsyncIterable`. * - * **Not to be confused with `isAsynchronousIterable` which checks for both - * `AsyncIterable` and `Iterable`.** + * > [!IMPORTANT] + * > Not to be confused with `isAwaitableIterable` which checks for both + * > `AsyncIterable` and `Iterable`. * * @example * ```typescript diff --git a/@coven/predicates/isAwaitableIterable.ts b/@coven/predicates/isAwaitableIterable.ts index c21a36c..039a5e6 100644 --- a/@coven/predicates/isAwaitableIterable.ts +++ b/@coven/predicates/isAwaitableIterable.ts @@ -3,16 +3,17 @@ import { isAsyncIterable } from "./isAsyncIterable.ts"; import { isIterable } from "./isIterable.ts"; /** - * Check if given value is `IsomorphicIterable` (either `Iterable` or + * Check if given value is `AwaitableIterable` (either `Iterable` or * `AsyncIterable`). * - * **Not to be confused with `isAsyncIterable` which only checks for - * `AsyncIterable`.** + * > [!IMPORTANT] + * > Not to be confused with `isAsyncIterable` which only checks for + * > `AsyncIterable` * * @example * ```typescript - * isIterable([]); // true - * isIterable({}); // false + * isAwaitableIterable([]); // true + * isAwaitableIterable({}); // false * ``` * @param input Value to check. * @returns `true` when is an `IsomorphicIterable`, `false` otherwise. diff --git a/@coven/predicates/isBigInt.ts b/@coven/predicates/isBigInt.ts index 6b25fdb..2534a72 100644 --- a/@coven/predicates/isBigInt.ts +++ b/@coven/predicates/isBigInt.ts @@ -2,7 +2,7 @@ import { isType } from "./isType.ts"; import type { IsTypeFunction } from "./IsTypeFunction.ts"; /** - * `typeof` "bigint" alias. + * `typeof value === "bigint"` check. * * @example * ```typescript diff --git a/@coven/predicates/isBoolean.ts b/@coven/predicates/isBoolean.ts index 1764dc1..8b9575f 100644 --- a/@coven/predicates/isBoolean.ts +++ b/@coven/predicates/isBoolean.ts @@ -2,7 +2,7 @@ import { isType } from "./isType.ts"; import type { IsTypeFunction } from "./IsTypeFunction.ts"; /** - * `typeof` "boolean" alias. + * `typeof value === "boolean"` check. * * @example * ```typescript diff --git a/@coven/predicates/isDate.ts b/@coven/predicates/isDate.ts index 31c34c2..058a98a 100644 --- a/@coven/predicates/isDate.ts +++ b/@coven/predicates/isDate.ts @@ -2,12 +2,12 @@ import { isInstanceOf } from "./isInstanceOf.ts"; import type { IsInstanceOfFunction } from "./IsInstanceOfFunction.ts"; /** - * `instanceof Date` alias. + * `value instanceof Date` check. * * @example * ```typescript - * isBigInt(1n); // true - * isBigInt(1); // false + * isDate(new Date()); // true + * isDate("1989-10-13"); // false * ``` * @returns `true` if the given value is a `Date`, `false` otherwise. */ diff --git a/@coven/predicates/isFunction.ts b/@coven/predicates/isFunction.ts index cd4ef93..cab0f61 100644 --- a/@coven/predicates/isFunction.ts +++ b/@coven/predicates/isFunction.ts @@ -2,7 +2,7 @@ import { isType } from "./isType.ts"; import type { IsTypeFunction } from "./IsTypeFunction.ts"; /** - * `typeof` "function" alias. + * `typeof value === "function"` check. * * @example * ```typescript diff --git a/@coven/predicates/isInstanceOf.ts b/@coven/predicates/isInstanceOf.ts index 9d7ade3..ebf0959 100644 --- a/@coven/predicates/isInstanceOf.ts +++ b/@coven/predicates/isInstanceOf.ts @@ -6,7 +6,7 @@ import type { IsInstanceOfFunction } from "./IsInstanceOfFunction.ts"; * * @example * ```typescript - * const instanceOfArray = instanceOf(Array) + * const instanceOfArray = isInstanceOf(Array) * * instanceOfArray([]); // true * instanceOfArray({}); // false diff --git a/@coven/predicates/isNull.ts b/@coven/predicates/isNull.ts index 9bbb2c9..bcc0d99 100644 --- a/@coven/predicates/isNull.ts +++ b/@coven/predicates/isNull.ts @@ -2,9 +2,12 @@ import { isType } from "./isType.ts"; import type { IsTypeFunction } from "./IsTypeFunction.ts"; /** - * `typeof` "null" alias. This "patches" typeof so `null` is not `"object"` but - * `"null"` instead (rejected proposal for lack of backwards compatibility, more - * details [here](https://lou.cx/null-typeof)). + * `typeof value === "null"` check. + * + * > [!IMPORTANT] + * > This "patches" typeof so `null` is not `"object"` but `"null"` instead + * > (rejected proposal for lack of backwards compatibility, more details + * > [here](https://lou.cx/null-typeof)). * * @example * ```typescript diff --git a/@coven/predicates/isNumber.ts b/@coven/predicates/isNumber.ts index d7b9087..bd3a705 100644 --- a/@coven/predicates/isNumber.ts +++ b/@coven/predicates/isNumber.ts @@ -2,7 +2,7 @@ import { isType } from "./isType.ts"; import type { IsTypeFunction } from "./IsTypeFunction.ts"; /** - * `typeof` "number" alias. + * `typeof value === "number"` check. * * @example * ```typescript diff --git a/@coven/predicates/isObject.ts b/@coven/predicates/isObject.ts index b4dbc01..3ddd038 100644 --- a/@coven/predicates/isObject.ts +++ b/@coven/predicates/isObject.ts @@ -2,7 +2,10 @@ import { isType } from "./isType.ts"; import type { IsTypeFunction } from "./IsTypeFunction.ts"; /** - * `typeof` "object" alias. + * `typeof value === "object"` check. + * + * > [!IMPORTANT] + * > This will return `false` for `null`, use `isNull` instead. * * @example * ```typescript diff --git a/@coven/predicates/isPromise.ts b/@coven/predicates/isPromise.ts index 4691c6c..0642b02 100644 --- a/@coven/predicates/isPromise.ts +++ b/@coven/predicates/isPromise.ts @@ -2,13 +2,12 @@ import { isInstanceOf } from "./isInstanceOf.ts"; import type { IsInstanceOfFunction } from "./IsInstanceOfFunction.ts"; /** - * `instanceof Promise` alias. + * `value instanceof Promise` check. * * @example * ```typescript - * isPromise(new Promise()); // true + * isPromise(new Promise(resolve => resolve(""))); // true * isPromise((async () => {})()); // true - * isPromise(fetch("https://coven.engineering")); // true * isPromise(Promise.resolve("Coven")); // true * isPromise("Coven"); // false * ``` diff --git a/@coven/predicates/isPropertyKey.ts b/@coven/predicates/isPropertyKey.ts index 5bbf1fd..b965fad 100644 --- a/@coven/predicates/isPropertyKey.ts +++ b/@coven/predicates/isPropertyKey.ts @@ -3,7 +3,8 @@ import { isString } from "./isString.ts"; import { isSymbol } from "./isSymbol.ts"; /** - * Checks if the given value is a valid PropertyKey of an object (`string`, `symbol`, or `number`). + * Checks if the given value is a valid PropertyKey for an object (`string`, + * `symbol`, or `number`). * * @example * ```typescript diff --git a/@coven/predicates/isPropertyOf.ts b/@coven/predicates/isPropertyOf.ts index 54f5d2e..695bcdd 100644 --- a/@coven/predicates/isPropertyOf.ts +++ b/@coven/predicates/isPropertyOf.ts @@ -5,9 +5,9 @@ import type { ReadonlyRecord } from "@coven/types"; * * @example * ```typescript - * const isPropertyOfFoo = isPropertyOf({ "🟢": "🟩" }); - * isPropertyOfFoo("🟢"); // true - * isPropertyOfFoo("🟩"); // false + * const isPropertyOfFoo = isPropertyOf({ "🧙🏻‍♀️": "🎃" } as Record); + * isPropertyOfFoo("🧙🏻‍♀️"); // true + * isPropertyOfFoo("🎃"); // false * ``` * @param object Object to check. * @returns Curried function with `context` set. diff --git a/@coven/predicates/isRegExp.ts b/@coven/predicates/isRegExp.ts index 1f124cd..3983035 100644 --- a/@coven/predicates/isRegExp.ts +++ b/@coven/predicates/isRegExp.ts @@ -2,7 +2,7 @@ import { isInstanceOf } from "./isInstanceOf.ts"; import type { IsInstanceOfFunction } from "./IsInstanceOfFunction.ts"; /** - * `instanceof RegExp` alias. + * `value instanceof RegExp` check. * * @example * ```typescript diff --git a/@coven/predicates/isSafeInteger.ts b/@coven/predicates/isSafeInteger.ts deleted file mode 100644 index 4611830..0000000 --- a/@coven/predicates/isSafeInteger.ts +++ /dev/null @@ -1,15 +0,0 @@ -import type { Unary } from "@coven/types"; - -/** - * Check if value passed is a safe integer. - * - * @example - * ```typescript - * isSafeInteger(13); // true - * isSafeInteger(10.13); // false - * ``` - */ -export const isSafeInteger = Number.isSafeInteger as Unary< - [value: number], - boolean ->; diff --git a/@coven/predicates/isString.ts b/@coven/predicates/isString.ts index eab92f6..42c1443 100644 --- a/@coven/predicates/isString.ts +++ b/@coven/predicates/isString.ts @@ -2,7 +2,7 @@ import { isType } from "./isType.ts"; import type { IsTypeFunction } from "./IsTypeFunction.ts"; /** - * `typeof` "string" alias. + * `typeof value === "string"` check. * * @example * ```typescript diff --git a/@coven/predicates/isSymbol.ts b/@coven/predicates/isSymbol.ts index 17be89d..b1ab435 100644 --- a/@coven/predicates/isSymbol.ts +++ b/@coven/predicates/isSymbol.ts @@ -2,7 +2,7 @@ import { isType } from "./isType.ts"; import type { IsTypeFunction } from "./IsTypeFunction.ts"; /** - * `typeof` "symbol" alias. + * `typeof value === "symbol"` check. * * @example * ```typescript diff --git a/@coven/predicates/isType.ts b/@coven/predicates/isType.ts index 19bee6f..e311d65 100644 --- a/@coven/predicates/isType.ts +++ b/@coven/predicates/isType.ts @@ -2,10 +2,12 @@ import type { TypeOfDictionary, TypeOfValue } from "@coven/types"; import type { IsTypeFunction } from "./IsTypeFunction.ts"; /** - * Takes a `type` string and checks if given `input` is of that `typeof`. This - * "patches" typeof so `null` is not `"object"` but `"null"` instead (rejected - * proposal for lack of backwards compatibility, more details - * [here](https://lou.cx/null-typeof)). + * Takes a `type` string and checks if given `input` is of that `typeof`. + * + * > [!IMPORTANT] + * > This "patches" typeof so `null` is not `"object"` but `"null"` instead + * > (rejected proposal for lack of backwards compatibility, more details + * > [here](https://lou.cx/null-typeof)). * * @example * ```typescript diff --git a/@coven/predicates/isUndefined.ts b/@coven/predicates/isUndefined.ts index 300a58e..0157f39 100644 --- a/@coven/predicates/isUndefined.ts +++ b/@coven/predicates/isUndefined.ts @@ -2,7 +2,7 @@ import { isType } from "./isType.ts"; import type { IsTypeFunction } from "./IsTypeFunction.ts"; /** - * `typeof` "undefined" alias. + * `typeof value === "undefined"` check. * * @example * ```typescript diff --git a/@coven/predicates/mod.ts b/@coven/predicates/mod.ts index 26b9bbb..f126ea6 100644 --- a/@coven/predicates/mod.ts +++ b/@coven/predicates/mod.ts @@ -27,7 +27,6 @@ export { isPrototypeOf } from "./isPrototypeOf.ts"; export type { IsPrototypeOfFunction } from "./IsPrototypeOfFunction.ts"; export { isPrototypeOfObject } from "./isPrototypeOfObject.ts"; export { isRegExp } from "./isRegExp.ts"; -export { isSafeInteger } from "./isSafeInteger.ts"; export { isString } from "./isString.ts"; export { isSymbol } from "./isSymbol.ts"; export { isTruthy } from "./isTruthy.ts"; diff --git a/@coven/predicates/test.ts b/@coven/predicates/test.ts index defcf89..b1a1495 100644 --- a/@coven/predicates/test.ts +++ b/@coven/predicates/test.ts @@ -1,7 +1,8 @@ import { attempt } from "@coven/parsers"; /** - * Given a regular expression and a string, returns `true` if the string matches the regular expression. + * Given a regular expression and a string, returns `true` if the string matches + * the regular expression. * * @example * ```typescript diff --git a/@coven/terminal/CurriedFormat.ts b/@coven/terminal/CurriedFormat.ts index 2211a6f..bd17d28 100644 --- a/@coven/terminal/CurriedFormat.ts +++ b/@coven/terminal/CurriedFormat.ts @@ -10,9 +10,28 @@ import type { FormattedString } from "./FormattedString.ts"; * @template Open Open code. * @template Close Close code. */ -export type CurriedFormat = < - Input extends string | TemplateStringsArray, ->( - input: Input, - ...expressions: ReadonlyArray -) => FormattedString; +export type CurriedFormat = { + /** + * Function that takes a `string` and returns a {@linkcode FormattedString}. + * + * @param string String to be wrapped with `Open` and `Close`. + */ + (string: String): FormattedString< + Open, + Close, + String + >; + /** + * Tagger function that takes a string literal and returns a + * {@linkcode FormattedString}. The type of the string part sadly can't be + * inferred. + * + * @param templateStringArray Array provided by string literal. + * @param expressions Expressions passed to the string literal (has to be + * stringable). + */ + ( + templateStringArray: TemplateStringsArray, + ...expressions: ReadonlyArray + ): FormattedString; +}; diff --git a/@coven/terminal/FormattedString.ts b/@coven/terminal/FormattedString.ts index 93e2b46..188f070 100644 --- a/@coven/terminal/FormattedString.ts +++ b/@coven/terminal/FormattedString.ts @@ -1,4 +1,3 @@ -import type { Fallback, ReadonlyTemplateStringsArray } from "@coven/types"; import type { sgr } from "./sgr.ts"; /** @@ -14,9 +13,5 @@ import type { sgr } from "./sgr.ts"; export type FormattedString< Open extends number, Close extends number, - Input extends string | TemplateStringsArray, -> = `${ReturnType>}${Fallback< - ReadonlyTemplateStringsArray, - Input, - string ->}${ReturnType>}`; + Input extends string = string, +> = `${ReturnType>}${Input}${ReturnType>}`; diff --git a/@coven/terminal/README.md b/@coven/terminal/README.md index 400a746..36e9aec 100644 --- a/@coven/terminal/README.md +++ b/@coven/terminal/README.md @@ -3,7 +3,7 @@ [![JSR](https://jsr.io/badges/@coven/terminal)](https://jsr.io/@coven/terminal) [![JSR Score](https://jsr.io/badges/@coven/terminal/score)](https://jsr.io/@coven/terminal/score) -🖌️ Delightfully simple terminal text styles. +🌈 Terminal ANSI colors utilities. `@coven/terminal` uses [ANSI escape codes][ansi-escape-code] to format CLI text background, color and style. The utils can be used as tag functions for @@ -32,24 +32,24 @@ bold("Example") === bold`Example`; These functions set the foreground and background color of a string. The full list of available foreground and background functions: -| Color | Foreground | Background | -| -------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | ------------------- | -| ![Black](https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/terminal/colors/black.svg) Black | `black` | `blackBack` | -| ![White](https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/terminal/colors/white.svg) White | `white` | `whiteBack` | -| ![Gray](https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/terminal/colors/gray.svg) Gray | `gray` | `grayBack` | -| ![Bright gray](https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/terminal/colors/brightGray.svg) Bright Gray | `brightGray` | `brightGrayBack` | -| ![Red](https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/terminal/colors/red.svg) Red | `red` | `redBack` | -| ![Bright red](https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/terminal/colors/brightRed.svg) Bright Red | `brightRed` | `brightRedBack` | -| ![Yellow](https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/terminal/colors/yellow.svg) Yellow | `yellow` | `yellowBack` | -| ![Bright yellow](https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/terminal/colors/brightYellow.svg) Bright Yellow | `brightYellow` | `brightYellowBack` | -| ![Green](https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/terminal/colors/green.svg) Green | `green` | `greenBack` | -| ![Bright green](https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/terminal/colors/brightGreen.svg) Bright Green | `brightGreen` | `brightGreenBack` | -| ![Cyan](https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/terminal/colors/cyan.svg) Cyan | `cyan` | `cyanBack` | -| ![Bright cyan](https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/terminal/colors/brightCyan.svg) Bright Cyan | `brightCyan` | `brightCyanBack` | -| ![Blue](https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/terminal/colors/blue.svg) Blue | `blue` | `blueBack` | -| ![Bright blue](https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/terminal/colors/brightBlue.svg) Bright Blue | `brightBlue` | `brightBlueBack` | -| ![Magenta](https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/terminal/colors/magenta.svg) Magenta | `magenta` | `magentaBack` | -| ![Bright magenta](https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/terminal/colors/brightMagenta.svg) Bright Magenta | `brightMagenta` | `brightMagentaBack` | +| Color | Foreground | Background | +| -------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | ----------------- | +| ![Black](https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/terminal/colors/black.svg) Black | `black` | `bgBlack` | +| ![White](https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/terminal/colors/white.svg) White | `white` | `bgWhite` | +| ![Gray](https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/terminal/colors/gray.svg) Gray | `gray` | `bgGray` | +| ![Bright gray](https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/terminal/colors/brightGray.svg) Bright Gray | `brightGray` | `bgBrightGray` | +| ![Red](https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/terminal/colors/red.svg) Red | `red` | `bgRed` | +| ![Bright red](https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/terminal/colors/brightRed.svg) Bright Red | `brightRed` | `bgBrightRed` | +| ![Yellow](https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/terminal/colors/yellow.svg) Yellow | `yellow` | `bgYellow` | +| ![Bright yellow](https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/terminal/colors/brightYellow.svg) Bright Yellow | `brightYellow` | `bgBrightYellow` | +| ![Green](https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/terminal/colors/green.svg) Green | `green` | `bgGreen` | +| ![Bright green](https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/terminal/colors/brightGreen.svg) Bright Green | `brightGreen` | `bgBrightGreen` | +| ![Cyan](https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/terminal/colors/cyan.svg) Cyan | `cyan` | `bgCyan` | +| ![Bright cyan](https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/terminal/colors/brightCyan.svg) Bright Cyan | `brightCyan` | `bgBrightCyan` | +| ![Blue](https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/terminal/colors/blue.svg) Blue | `blue` | `bgBlue` | +| ![Bright blue](https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/terminal/colors/brightBlue.svg) Bright Blue | `brightBlue` | `bgBrightBlue` | +| ![Magenta](https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/terminal/colors/magenta.svg) Magenta | `magenta` | `bgMagenta` | +| ![Bright magenta](https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/terminal/colors/brightMagenta.svg) Bright Magenta | `brightMagenta` | `bgBrightMagenta` | ### Style Functions @@ -69,11 +69,11 @@ These functions apply various text styles: The library includes a `mix` function that can be used to mix several utils: ```typescript -import { bold, mix, red, whiteBack } from "@coven/terminal"; +import { bgWhite, bold, mix, red } from "@coven/terminal"; -const boldRedWhiteBack = mix(bold, red, whiteBack); +const example = mix(bold, red, bgWhite); -boldRedWhiteBack`Coven Engineering`; // The string "Coven Engineering", with bold style, red color and white background +example`Coven Engineering`; // The string "Coven Engineering", with bold style, red color and white background ``` As all [Coven Engineering](https://coven.engineering) libraries, it has 100% diff --git a/@coven/terminal/blackBack.ts b/@coven/terminal/bgBlack.ts similarity index 76% rename from @coven/terminal/blackBack.ts rename to @coven/terminal/bgBlack.ts index 0c9b08e..f85ff22 100644 --- a/@coven/terminal/blackBack.ts +++ b/@coven/terminal/bgBlack.ts @@ -10,12 +10,12 @@ import { format } from "./format.ts"; * * @example * ```typescript - * blackBack("Coven"); // "\u001B[40mCoven\u001B[49m" + * bgBlack("Coven"); // "\u001B[40mCoven\u001B[49m" * // It can also be used as a tag function for tagged templates: - * blackBack`Coven`; // "\u001B[40mCoven\u001B[49m" + * bgBlack`Coven`; // "\u001B[40mCoven\u001B[49m" * ``` * @see {@linkcode format} * @see {@linkcode Background} * @see [3-bit and 4-bit ANSI colors](https://en.wikipedia.org/wiki/ANSI_escape_code#3-bit_and_4-bit) */ -export const blackBack: Background<40> = format(40, CLOSE_BACKGROUND); +export const bgBlack: Background<40> = format(40, CLOSE_BACKGROUND); diff --git a/@coven/terminal/blueBack.ts b/@coven/terminal/bgBlue.ts similarity index 76% rename from @coven/terminal/blueBack.ts rename to @coven/terminal/bgBlue.ts index d1ee5ff..87bddb5 100644 --- a/@coven/terminal/blueBack.ts +++ b/@coven/terminal/bgBlue.ts @@ -10,12 +10,12 @@ import { format } from "./format.ts"; * * @example * ```typescript - * blueBack("Coven"); // "\u001B[44mCoven\u001B[49m" + * bgBlue("Coven"); // "\u001B[44mCoven\u001B[49m" * // It can also be used as a tag function for tagged templates: - * blueBack`Coven`; // "\u001B[44mCoven\u001B[49m" + * bgBlue`Coven`; // "\u001B[44mCoven\u001B[49m" * ``` * @see {@linkcode format} * @see {@linkcode Background} * @see [3-bit and 4-bit ANSI colors](https://en.wikipedia.org/wiki/ANSI_escape_code#3-bit_and_4-bit) */ -export const blueBack: Background<44> = format(44, CLOSE_BACKGROUND); +export const bgBlue: Background<44> = format(44, CLOSE_BACKGROUND); diff --git a/@coven/terminal/brightBlueBack.ts b/@coven/terminal/bgBrightBlue.ts similarity index 74% rename from @coven/terminal/brightBlueBack.ts rename to @coven/terminal/bgBrightBlue.ts index 8585dbc..1b01696 100644 --- a/@coven/terminal/brightBlueBack.ts +++ b/@coven/terminal/bgBrightBlue.ts @@ -10,12 +10,12 @@ import { format } from "./format.ts"; * * @example * ```typescript - * brightBlueBack("Coven"); // "\u001B[104mCoven\u001B[49m" + * bgBrightBlue("Coven"); // "\u001B[104mCoven\u001B[49m" * // It can also be used as a tag function for tagged templates: - * brightBlueBack`Coven`; // "\u001B[104mCoven\u001B[49m" + * bgBrightBlue`Coven`; // "\u001B[104mCoven\u001B[49m" * ``` * @see {@linkcode format} * @see {@linkcode Background} * @see [3-bit and 4-bit ANSI colors](https://en.wikipedia.org/wiki/ANSI_escape_code#3-bit_and_4-bit) */ -export const brightBlueBack: Background<104> = format(104, CLOSE_BACKGROUND); +export const bgBrightBlue: Background<104> = format(104, CLOSE_BACKGROUND); diff --git a/@coven/terminal/brightCyanBack.ts b/@coven/terminal/bgBrightCyan.ts similarity index 74% rename from @coven/terminal/brightCyanBack.ts rename to @coven/terminal/bgBrightCyan.ts index 076ad7d..d96a9f5 100644 --- a/@coven/terminal/brightCyanBack.ts +++ b/@coven/terminal/bgBrightCyan.ts @@ -10,12 +10,12 @@ import { format } from "./format.ts"; * * @example * ```typescript - * brightCyanBack("Coven"); // "\u001B[106mCoven\u001B[49m" + * bgBrightCyan("Coven"); // "\u001B[106mCoven\u001B[49m" * // It can also be used as a tag function for tagged templates: - * brightCyanBack`Coven`; // "\u001B[106mCoven\u001B[49m" + * bgBrightCyan`Coven`; // "\u001B[106mCoven\u001B[49m" * ``` * @see {@linkcode format} * @see {@linkcode Background} * @see [3-bit and 4-bit ANSI colors](https://en.wikipedia.org/wiki/ANSI_escape_code#3-bit_and_4-bit) */ -export const brightCyanBack: Background<106> = format(106, CLOSE_BACKGROUND); +export const bgBrightCyan: Background<106> = format(106, CLOSE_BACKGROUND); diff --git a/@coven/terminal/brightGrayBack.ts b/@coven/terminal/bgBrightGray.ts similarity index 74% rename from @coven/terminal/brightGrayBack.ts rename to @coven/terminal/bgBrightGray.ts index c51464c..f47d336 100644 --- a/@coven/terminal/brightGrayBack.ts +++ b/@coven/terminal/bgBrightGray.ts @@ -10,12 +10,12 @@ import { format } from "./format.ts"; * * @example * ```typescript - * brightGrayBack("Coven"); // "\u001B[107mCoven\u001B[49m" + * bgBrightGray("Coven"); // "\u001B[107mCoven\u001B[49m" * // It can also be used as a tag function for tagged templates: - * brightGrayBack`Coven`; // "\u001B[107mCoven\u001B[49m" + * bgBrightGray`Coven`; // "\u001B[107mCoven\u001B[49m" * ``` * @see {@linkcode format} * @see {@linkcode Background} * @see [3-bit and 4-bit ANSI colors](https://en.wikipedia.org/wiki/ANSI_escape_code#3-bit_and_4-bit) */ -export const brightGrayBack: Background<107> = format(107, CLOSE_BACKGROUND); +export const bgBrightGray: Background<107> = format(107, CLOSE_BACKGROUND); diff --git a/@coven/terminal/brightGreenBack.ts b/@coven/terminal/bgBrightGreen.ts similarity index 74% rename from @coven/terminal/brightGreenBack.ts rename to @coven/terminal/bgBrightGreen.ts index 9faf7d5..f718ad2 100644 --- a/@coven/terminal/brightGreenBack.ts +++ b/@coven/terminal/bgBrightGreen.ts @@ -10,12 +10,12 @@ import { format } from "./format.ts"; * * @example * ```typescript - * brightGreenBack("Coven"); // "\u001B[102mCoven\u001B[49m" + * bgBrightGreen("Coven"); // "\u001B[102mCoven\u001B[49m" * // It can also be used as a tag function for tagged templates: - * brightGreenBack`Coven`; // "\u001B[102mCoven\u001B[49m" + * bgBrightGreen`Coven`; // "\u001B[102mCoven\u001B[49m" * ``` * @see {@linkcode format} * @see {@linkcode Background} * @see [3-bit and 4-bit ANSI colors](https://en.wikipedia.org/wiki/ANSI_escape_code#3-bit_and_4-bit) */ -export const brightGreenBack: Background<102> = format(102, CLOSE_BACKGROUND); +export const bgBrightGreen: Background<102> = format(102, CLOSE_BACKGROUND); diff --git a/@coven/terminal/brightMagentaBack.ts b/@coven/terminal/bgBrightMagenta.ts similarity index 74% rename from @coven/terminal/brightMagentaBack.ts rename to @coven/terminal/bgBrightMagenta.ts index 2cc855b..6576530 100644 --- a/@coven/terminal/brightMagentaBack.ts +++ b/@coven/terminal/bgBrightMagenta.ts @@ -10,12 +10,12 @@ import { format } from "./format.ts"; * * @example * ```typescript - * brightMagentaBack("Coven"); // "\u001B[105mCoven\u001B[49m" + * bgBrightMagenta("Coven"); // "\u001B[105mCoven\u001B[49m" * // It can also be used as a tag function for tagged templates: - * brightMagentaBack`Coven`; // "\u001B[105mCoven\u001B[49m" + * bgBrightMagenta`Coven`; // "\u001B[105mCoven\u001B[49m" * ``` * @see {@linkcode format} * @see {@linkcode Background} * @see [3-bit and 4-bit ANSI colors](https://en.wikipedia.org/wiki/ANSI_escape_code#3-bit_and_4-bit) */ -export const brightMagentaBack: Background<105> = format(105, CLOSE_BACKGROUND); +export const bgBrightMagenta: Background<105> = format(105, CLOSE_BACKGROUND); diff --git a/@coven/terminal/brightRedBack.ts b/@coven/terminal/bgBrightRed.ts similarity index 75% rename from @coven/terminal/brightRedBack.ts rename to @coven/terminal/bgBrightRed.ts index f1578db..595c33d 100644 --- a/@coven/terminal/brightRedBack.ts +++ b/@coven/terminal/bgBrightRed.ts @@ -10,12 +10,12 @@ import { format } from "./format.ts"; * * @example * ```typescript - * brightRedBack("Coven"); // "\u001B[101mCoven\u001B[49m" + * bgBrightRed("Coven"); // "\u001B[101mCoven\u001B[49m" * // It can also be used as a tag function for tagged templates: - * brightRedBack`Coven`; // "\u001B[101mCoven\u001B[49m" + * bgBrightRed`Coven`; // "\u001B[101mCoven\u001B[49m" * ``` * @see {@linkcode format} * @see {@linkcode Background} * @see [3-bit and 4-bit ANSI colors](https://en.wikipedia.org/wiki/ANSI_escape_code#3-bit_and_4-bit) */ -export const brightRedBack: Background<101> = format(101, CLOSE_BACKGROUND); +export const bgBrightRed: Background<101> = format(101, CLOSE_BACKGROUND); diff --git a/@coven/terminal/brightYellowBack.ts b/@coven/terminal/bgBrightYellow.ts similarity index 74% rename from @coven/terminal/brightYellowBack.ts rename to @coven/terminal/bgBrightYellow.ts index 1dd69dc..9b78a4f 100644 --- a/@coven/terminal/brightYellowBack.ts +++ b/@coven/terminal/bgBrightYellow.ts @@ -10,12 +10,12 @@ import { format } from "./format.ts"; * * @example * ```typescript - * brightYellowBack("Coven"); // "\u001B[103mCoven\u001B[49m" + * bgBrightYellow("Coven"); // "\u001B[103mCoven\u001B[49m" * // It can also be used as a tag function for tagged templates: - * brightYellowBack`Coven`; // "\u001B[103mCoven\u001B[49m" + * bgBrightYellow`Coven`; // "\u001B[103mCoven\u001B[49m" * ``` * @see {@linkcode format} * @see {@linkcode Background} * @see [3-bit and 4-bit ANSI colors](https://en.wikipedia.org/wiki/ANSI_escape_code#3-bit_and_4-bit) */ -export const brightYellowBack: Background<103> = format(103, CLOSE_BACKGROUND); +export const bgBrightYellow: Background<103> = format(103, CLOSE_BACKGROUND); diff --git a/@coven/terminal/cyanBack.ts b/@coven/terminal/bgCyan.ts similarity index 76% rename from @coven/terminal/cyanBack.ts rename to @coven/terminal/bgCyan.ts index e3d020b..c449ff3 100644 --- a/@coven/terminal/cyanBack.ts +++ b/@coven/terminal/bgCyan.ts @@ -10,12 +10,12 @@ import { format } from "./format.ts"; * * @example * ```typescript - * cyanBack("Coven"); // "\u001B[46mCoven\u001B[49m" + * bgCyan("Coven"); // "\u001B[46mCoven\u001B[49m" * // It can also be used as a tag function for tagged templates: - * cyanBack`Coven`; // "\u001B[46mCoven\u001B[49m" + * bgCyan`Coven`; // "\u001B[46mCoven\u001B[49m" * ``` * @see {@linkcode format} * @see {@linkcode Background} * @see [3-bit and 4-bit ANSI colors](https://en.wikipedia.org/wiki/ANSI_escape_code#3-bit_and_4-bit) */ -export const cyanBack: Background<46> = format(46, CLOSE_BACKGROUND); +export const bgCyan: Background<46> = format(46, CLOSE_BACKGROUND); diff --git a/@coven/terminal/grayBack.ts b/@coven/terminal/bgGray.ts similarity index 76% rename from @coven/terminal/grayBack.ts rename to @coven/terminal/bgGray.ts index 5e5ec88..f853f6a 100644 --- a/@coven/terminal/grayBack.ts +++ b/@coven/terminal/bgGray.ts @@ -10,12 +10,12 @@ import { format } from "./format.ts"; * * @example * ```typescript - * grayBack("Coven"); // "\u001B[100mCoven\u001B[49m" + * bgGray("Coven"); // "\u001B[100mCoven\u001B[49m" * // It can also be used as a tag function for tagged templates: - * grayBack`Coven`; // "\u001B[100mCoven\u001B[49m" + * bgGray`Coven`; // "\u001B[100mCoven\u001B[49m" * ``` * @see {@linkcode format} * @see {@linkcode Background} * @see [3-bit and 4-bit ANSI colors](https://en.wikipedia.org/wiki/ANSI_escape_code#3-bit_and_4-bit) */ -export const grayBack: Background<100> = format(100, CLOSE_BACKGROUND); +export const bgGray: Background<100> = format(100, CLOSE_BACKGROUND); diff --git a/@coven/terminal/greenBack.ts b/@coven/terminal/bgGreen.ts similarity index 76% rename from @coven/terminal/greenBack.ts rename to @coven/terminal/bgGreen.ts index 2113f9f..82cb77b 100644 --- a/@coven/terminal/greenBack.ts +++ b/@coven/terminal/bgGreen.ts @@ -10,12 +10,12 @@ import { format } from "./format.ts"; * * @example * ```typescript - * greenBack("Coven"); // "\u001B[42mCoven\u001B[49m" + * bgGreen("Coven"); // "\u001B[42mCoven\u001B[49m" * // It can also be used as a tag function for tagged templates: - * greenBack`Coven`; // "\u001B[42mCoven\u001B[49m" + * bgGreen`Coven`; // "\u001B[42mCoven\u001B[49m" * ``` * @see {@linkcode format} * @see {@linkcode Background} * @see [3-bit and 4-bit ANSI colors](https://en.wikipedia.org/wiki/ANSI_escape_code#3-bit_and_4-bit) */ -export const greenBack: Background<42> = format(42, CLOSE_BACKGROUND); +export const bgGreen: Background<42> = format(42, CLOSE_BACKGROUND); diff --git a/@coven/terminal/magentaBack.ts b/@coven/terminal/bgMagenta.ts similarity index 76% rename from @coven/terminal/magentaBack.ts rename to @coven/terminal/bgMagenta.ts index 0523181..be7059c 100644 --- a/@coven/terminal/magentaBack.ts +++ b/@coven/terminal/bgMagenta.ts @@ -10,12 +10,12 @@ import { format } from "./format.ts"; * * @example * ```typescript - * magentaBack("Lou"); // "\u001B[45mLou\u001B[49m" + * bgMagenta("Lou"); // "\u001B[45mLou\u001B[49m" * // It can also be used as a tag function for tagged templates: - * magentaBack`Lou`; // "\u001B[45mLou\u001B[49m" + * bgMagenta`Lou`; // "\u001B[45mLou\u001B[49m" * ``` * @see {@linkcode format} * @see {@linkcode Background} * @see [3-bit and 4-bit ANSI colors](https://en.wikipedia.org/wiki/ANSI_escape_code#3-bit_and_4-bit) */ -export const magentaBack: Background<45> = format(45, CLOSE_BACKGROUND); +export const bgMagenta: Background<45> = format(45, CLOSE_BACKGROUND); diff --git a/@coven/terminal/redBack.ts b/@coven/terminal/bgRed.ts similarity index 76% rename from @coven/terminal/redBack.ts rename to @coven/terminal/bgRed.ts index 915d631..46fa6d3 100644 --- a/@coven/terminal/redBack.ts +++ b/@coven/terminal/bgRed.ts @@ -10,12 +10,12 @@ import { format } from "./format.ts"; * * @example * ```typescript - * redBack("Coven"); // "\u001B[41mCoven\u001B[49m" + * bgRed("Coven"); // "\u001B[41mCoven\u001B[49m" * // It can also be used as a tag function for tagged templates: - * redBack`Coven`; // "\u001B[41mCoven\u001B[49m" + * bgRed`Coven`; // "\u001B[41mCoven\u001B[49m" * ``` * @see {@linkcode format} * @see {@linkcode Background} * @see [3-bit and 4-bit ANSI colors](https://en.wikipedia.org/wiki/ANSI_escape_code#3-bit_and_4-bit) */ -export const redBack: Background<41> = format(41, CLOSE_BACKGROUND); +export const bgRed: Background<41> = format(41, CLOSE_BACKGROUND); diff --git a/@coven/terminal/whiteBack.ts b/@coven/terminal/bgWhite.ts similarity index 76% rename from @coven/terminal/whiteBack.ts rename to @coven/terminal/bgWhite.ts index 5813aeb..f843273 100644 --- a/@coven/terminal/whiteBack.ts +++ b/@coven/terminal/bgWhite.ts @@ -10,12 +10,12 @@ import { format } from "./format.ts"; * * @example * ```typescript - * whiteBack("Coven"); // "\u001B[47mCoven\u001B[49m" + * bgWhite("Coven"); // "\u001B[47mCoven\u001B[49m" * // It can also be used as a tag function for tagged templates: - * whiteBack`Coven`; // "\u001B[47mCoven\u001B[49m" + * bgWhite`Coven`; // "\u001B[47mCoven\u001B[49m" * ``` * @see {@linkcode format} * @see {@linkcode Background} * @see [3-bit and 4-bit ANSI colors](https://en.wikipedia.org/wiki/ANSI_escape_code#3-bit_and_4-bit) */ -export const whiteBack: Background<47> = format(47, CLOSE_BACKGROUND); +export const bgWhite: Background<47> = format(47, CLOSE_BACKGROUND); diff --git a/@coven/terminal/yellowBack.ts b/@coven/terminal/bgYellow.ts similarity index 76% rename from @coven/terminal/yellowBack.ts rename to @coven/terminal/bgYellow.ts index 5484b0a..5af664c 100644 --- a/@coven/terminal/yellowBack.ts +++ b/@coven/terminal/bgYellow.ts @@ -10,12 +10,12 @@ import { format } from "./format.ts"; * * @example * ```typescript - * yellowBack("Coven"); // "\u001B[43mCoven\u001B[49m" + * bgYellow("Coven"); // "\u001B[43mCoven\u001B[49m" * // It can also be used as a tag function for tagged templates: - * yellowBack`Coven`; // "\u001B[43mCoven\u001B[49m" + * bgYellow`Coven`; // "\u001B[43mCoven\u001B[49m" * ``` * @see {@linkcode format} * @see {@linkcode Background} * @see [3-bit and 4-bit ANSI colors](https://en.wikipedia.org/wiki/ANSI_escape_code#3-bit_and_4-bit) */ -export const yellowBack: Background<43> = format(43, CLOSE_BACKGROUND); +export const bgYellow: Background<43> = format(43, CLOSE_BACKGROUND); diff --git a/@coven/terminal/deno.json b/@coven/terminal/deno.json index 204f521..1b00c0f 100644 --- a/@coven/terminal/deno.json +++ b/@coven/terminal/deno.json @@ -1,5 +1,5 @@ { "name": "@coven/terminal", - "version": "0.1.0", + "version": "0.3.0", "exports": "./mod.ts" } diff --git a/@coven/terminal/format.ts b/@coven/terminal/format.ts index eae0814..424a14c 100644 --- a/@coven/terminal/format.ts +++ b/@coven/terminal/format.ts @@ -1,3 +1,4 @@ +import type { ReadonlyArray, Stringable } from "@coven/types"; import type { FormatFunction } from "./FormatFunction.ts"; import { normalizeString } from "./normalizeString.ts"; import { sgr } from "./sgr.ts"; @@ -33,11 +34,13 @@ export const format = ((open, close) => { * @param expressions Input expressions (when using tagged templates) * @returns Formatted `input` string. */ - return (input, ...expressions) => - `${sgrOpen}${ - normalizeString(input, ...expressions).replaceAll( - sgrClose, - sgrOpen, - ) - }${sgrClose}`; + return ( + input: string | TemplateStringsArray, + ...expressions: ReadonlyArray + ) => `${sgrOpen}${ + normalizeString(input, ...expressions).replaceAll( + sgrClose, + sgrOpen, + ) + }${sgrClose}`; }) as FormatFunction; diff --git a/@coven/terminal/mix.ts b/@coven/terminal/mix.ts index 112eed4..c7e7b6d 100644 --- a/@coven/terminal/mix.ts +++ b/@coven/terminal/mix.ts @@ -9,13 +9,13 @@ import type { Formatter } from "./Formatter.ts"; * * @example * ```typescript - * import { red, whiteBack } from "@coven/terminal"; + * import { red, bgWhite } from "@coven/terminal"; * - * const redWhiteBack = mix(red, whiteBack); + * const mixed = mix(red, bgWhite); * - * redWhiteBack("Coven Engineering"); + * mixed("Coven Engineering"); * // It can also be used as a tag function for tagged templates: - * redWhiteBack`Coven Engineering`; + * mixed`Coven Engineering`; * ``` * @see {@linkcode Formatter} * @param formatters Array of formatters to be composed. diff --git a/@coven/terminal/mod.ts b/@coven/terminal/mod.ts index 2636a7a..be5d78d 100644 --- a/@coven/terminal/mod.ts +++ b/@coven/terminal/mod.ts @@ -1,28 +1,34 @@ export type { Background } from "./Background.ts"; +export { bgBlack } from "./bgBlack.ts"; +export { bgBlue } from "./bgBlue.ts"; +export { bgBrightBlue } from "./bgBrightBlue.ts"; +export { bgBrightCyan } from "./bgBrightCyan.ts"; +export { bgBrightGray } from "./bgBrightGray.ts"; +export { bgBrightGreen } from "./bgBrightGreen.ts"; +export { bgBrightMagenta } from "./bgBrightMagenta.ts"; +export { bgBrightRed } from "./bgBrightRed.ts"; +export { bgBrightYellow } from "./bgBrightYellow.ts"; +export { bgCyan } from "./bgCyan.ts"; +export { bgGray } from "./bgGray.ts"; +export { bgGreen } from "./bgGreen.ts"; +export { bgMagenta } from "./bgMagenta.ts"; +export { bgRed } from "./bgRed.ts"; +export { bgWhite } from "./bgWhite.ts"; +export { bgYellow } from "./bgYellow.ts"; export { black } from "./black.ts"; -export { blackBack } from "./blackBack.ts"; export { blue } from "./blue.ts"; -export { blueBack } from "./blueBack.ts"; export { bold } from "./bold.ts"; export { brightBlue } from "./brightBlue.ts"; -export { brightBlueBack } from "./brightBlueBack.ts"; export { brightCyan } from "./brightCyan.ts"; -export { brightCyanBack } from "./brightCyanBack.ts"; export { brightGray } from "./brightGray.ts"; -export { brightGrayBack } from "./brightGrayBack.ts"; export { brightGreen } from "./brightGreen.ts"; -export { brightGreenBack } from "./brightGreenBack.ts"; export { brightMagenta } from "./brightMagenta.ts"; -export { brightMagentaBack } from "./brightMagentaBack.ts"; export { brightRed } from "./brightRed.ts"; -export { brightRedBack } from "./brightRedBack.ts"; export { brightYellow } from "./brightYellow.ts"; -export { brightYellowBack } from "./brightYellowBack.ts"; export { CLOSE_BACKGROUND } from "./CLOSE_BACKGROUND.ts"; export { CLOSE_FOREGROUND } from "./CLOSE_FOREGROUND.ts"; export type { CurriedFormat } from "./CurriedFormat.ts"; export { cyan } from "./cyan.ts"; -export { cyanBack } from "./cyanBack.ts"; export { dimmed } from "./dimmed.ts"; export { ESCAPE } from "./ESCAPE.ts"; export type { Foreground } from "./Foreground.ts"; @@ -31,21 +37,15 @@ export type { FormatFunction } from "./FormatFunction.ts"; export type { FormattedString } from "./FormattedString.ts"; export type { Formatter } from "./Formatter.ts"; export { gray } from "./gray.ts"; -export { grayBack } from "./grayBack.ts"; export { green } from "./green.ts"; -export { greenBack } from "./greenBack.ts"; export { inverse } from "./inverse.ts"; export { italic } from "./italic.ts"; export { magenta } from "./magenta.ts"; -export { magentaBack } from "./magentaBack.ts"; export { mix } from "./mix.ts"; export { normalizeString } from "./normalizeString.ts"; export { red } from "./red.ts"; -export { redBack } from "./redBack.ts"; export { sgr } from "./sgr.ts"; export { strikethrough } from "./strikethrough.ts"; export { underlined } from "./underlined.ts"; export { white } from "./white.ts"; -export { whiteBack } from "./whiteBack.ts"; export { yellow } from "./yellow.ts"; -export { yellowBack } from "./yellowBack.ts"; diff --git a/@coven/types/Add.ts b/@coven/types/Add.ts index f2893bd..4c53945 100644 --- a/@coven/types/Add.ts +++ b/@coven/types/Add.ts @@ -3,14 +3,16 @@ import type { IndexArray } from "./IndexArray.ts"; import type { ReadonlyArray } from "./ReadonlyArray.ts"; /** - * Recursively generates the result of adding `Addend` to `Augend`. This is - * expensive and has the same limit TypeScript has for recursive types. + * Recursively generates the result of adding `Addend` to `Augend`. + * + * > [!IMPORTANT] + * > This is expensive and has the same limit TypeScript has for recursive types. * * @example * ```typescript * type thirteen = Add<10, 3>; // 13 * ``` - * @see {@link ReadonlyArray} + * @see {@linkcode ReadonlyArray} * @template Addend Addend of the add operation. * @template Augend Augend of the add operation. * @template _Accumulator **⚠️ INTERNAL:** Accumulator for the recursion. diff --git a/@coven/types/ArrayLikeIndexFallback.ts b/@coven/types/ArrayLikeIndexFallback.ts index 20a09e4..0312c5b 100644 --- a/@coven/types/ArrayLikeIndexFallback.ts +++ b/@coven/types/ArrayLikeIndexFallback.ts @@ -3,7 +3,7 @@ import type { NeverFallback } from "./NeverFallback.ts"; import type { ReadonlyArrayLike } from "./ReadonlyArrayLike.ts"; /** - * Gets the possible index values of a {@link ReadonlyArrayLike}, and fallbacks + * Gets the possible index values of a {@linkcode ReadonlyArrayLike}, and fallbacks * to `number` when it can't be inferred. * * @example @@ -14,9 +14,9 @@ import type { ReadonlyArrayLike } from "./ReadonlyArrayLike.ts"; * type IndexOfTriple = ArrayLikeIndexFallback; // 0 | 1 | 2 * type IndexOfArray = ArrayLikeIndexFallback; // number * ``` - * @see {@link Just} - * @see {@link NeverFallback} - * @see {@link ReadonlyArrayLike} + * @see {@linkcode Just} + * @see {@linkcode NeverFallback} + * @see {@linkcode ReadonlyArrayLike} * @template Array An array-like (we mainly care about it having a `length`). */ export type ArrayLikeIndexFallback< diff --git a/@coven/types/AwaitableEffect.ts b/@coven/types/AwaitableEffect.ts new file mode 100644 index 0000000..09e995f --- /dev/null +++ b/@coven/types/AwaitableEffect.ts @@ -0,0 +1,17 @@ +import type { Awaitable } from "./Awaitable.ts"; +import type { ReadonlyArray } from "./ReadonlyArray.ts"; + +/** + * Awaitable effect function. + * + * This function returns a Promise with a `void` value which means is not doing + * a data transformation, but instead running some kind of async side-effect. + * + * @example + * ```typescript + * const awaitableEffect = (input => Promise.resolve(console.log(input))) satisfies AwaitableEffect<[input: number]>; + * ``` + * @template Arguments Tuple of arguments. + */ +export type AwaitableEffect = Arguments extends + readonly [] ? () => Awaitable : (..._: Arguments) => Awaitable; diff --git a/@coven/types/AwaitableGenerator.ts b/@coven/types/AwaitableGenerator.ts index 82e461f..3485a85 100644 --- a/@coven/types/AwaitableGenerator.ts +++ b/@coven/types/AwaitableGenerator.ts @@ -3,7 +3,12 @@ * * @example * ```typescript - * // TODO: Example here + * const generator: AwaitableGenerator = (function* () { + * yield 13; + * })(); + * export const asyncGenerator: AwaitableGenerator = (async function* () { + * yield 13; + * })(); * ``` * @template Item Type of the items in the `AwaitableGenerator`. * @template Return Type of the return value in the `AwaitableGenerator`. diff --git a/@coven/types/AwaitableIterator.ts b/@coven/types/AwaitableIterator.ts index 802da12..68845f6 100644 --- a/@coven/types/AwaitableIterator.ts +++ b/@coven/types/AwaitableIterator.ts @@ -3,7 +3,7 @@ * * @example * ```typescript - * const iterator = [13, 42, 665] as const satisfies AwaitableIterator; + * const iterator = [13, 42, 665].values() satisfies AwaitableIterator; * ``` * @template Item Type of the items in the `AwaitableIterator`. * @template Return Type of the return value in the `AwaitableIterator`. diff --git a/@coven/types/Class.ts b/@coven/types/Class.ts index 6b8e095..b03f029 100644 --- a/@coven/types/Class.ts +++ b/@coven/types/Class.ts @@ -8,7 +8,7 @@ import type { ReadonlyArray } from "./ReadonlyArray.ts"; * ```typescript * const example = (AClass: Class) => new AClass("test"); * ``` - * @see {@link ReadonlyArray} + * @see {@linkcode ReadonlyArray} * @template Arguments Arguments of the class constructor. * @template Instance Instance of the class. */ diff --git a/@coven/types/DayOfMonth.ts b/@coven/types/DayOfMonth.ts index 0457cc5..fabd855 100644 --- a/@coven/types/DayOfMonth.ts +++ b/@coven/types/DayOfMonth.ts @@ -7,7 +7,7 @@ import type { Range } from "./Range.ts"; * ```typescript * const days = [1, 2, 3, 28, 29, 30, 31] as const satisfies Iterable; * ``` - * @see {@link Range} + * @see {@linkcode Range} * @see [Date](https://mdn.io/Date) */ export type DayOfMonth = Range<1, 31>; diff --git a/@coven/types/DayOfWeek.ts b/@coven/types/DayOfWeek.ts index 02561e8..939c616 100644 --- a/@coven/types/DayOfWeek.ts +++ b/@coven/types/DayOfWeek.ts @@ -7,7 +7,7 @@ import type { Enumerate } from "./Enumerate.ts"; * ```typescript * const daysOfWeek = [0, 1, 2, 3, 4, 5, 6] as const satisfies Iterable; * ``` - * @see {@link Enumerate} + * @see {@linkcode Enumerate} * @see [Date](https://mdn.io/Date) */ export type DayOfWeek = Enumerate<6>; diff --git a/@coven/types/Digit.ts b/@coven/types/Digit.ts index 19a22a5..23e37a3 100644 --- a/@coven/types/Digit.ts +++ b/@coven/types/Digit.ts @@ -9,6 +9,6 @@ import type { Enumerate } from "./Enumerate.ts"; * 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, * ] as const satisfies Iterable; * ``` - * @see {@link Enumerate} + * @see {@linkcode Enumerate} */ export type Digit = Enumerate<9>; diff --git a/@coven/types/Effect.ts b/@coven/types/Effect.ts new file mode 100644 index 0000000..018769c --- /dev/null +++ b/@coven/types/Effect.ts @@ -0,0 +1,16 @@ +import type { ReadonlyArray } from "./ReadonlyArray.ts"; + +/** + * Effect function. + * + * This function returns `void` which means is not doing a data transformation, + * but instead running some kind of side-effect. + * + * @example + * ```typescript + * const effect = (input => console.log(input)) satisfies Effect<[input: number]>; + * ``` + * @template Arguments Tuple of arguments. + */ +export type Effect = Arguments extends + readonly [] ? () => void : (..._: Arguments) => void; diff --git a/@coven/types/EntryKey.ts b/@coven/types/EntryKey.ts index 381f585..8f042de 100644 --- a/@coven/types/EntryKey.ts +++ b/@coven/types/EntryKey.ts @@ -1,14 +1,16 @@ import type { Entry } from "./Entry.ts"; /** - * Key of an {@link Entry}. + * Key of an {@linkcode Entry}. * * @example * ```typescript + * import type { Entry } from "@coven/types"; + * * const entry = ["🧙‍♀️", 13] as const satisfies Entry; * const entryKey = entry[0] satisfies EntryKey; * ``` - * @see {@link Entry} + * @see {@linkcode Entry} * @template EntryTuple Entry type. */ export type EntryKey = EntryTuple[0]; diff --git a/@coven/types/EntryOf.ts b/@coven/types/EntryOf.ts index 68d1e1c..3bd3f5c 100644 --- a/@coven/types/EntryOf.ts +++ b/@coven/types/EntryOf.ts @@ -3,7 +3,7 @@ import type { KeyOf } from "./KeyOf.ts"; import type { ReadonlyArrayLike } from "./ReadonlyArrayLike.ts"; /** - * Get the {@link Entry} of the passed object. + * Get the {@linkcode Entry} of the passed object. * * @example * ```typescript @@ -11,17 +11,17 @@ import type { ReadonlyArrayLike } from "./ReadonlyArrayLike.ts"; * "🧙‍♀️": 13, * "🔮": 42, * } as const; - * const entries = Object.entries(object)[0] satisfies EntryOf; + * const entries = Object.entries(object)[0] as EntryOf; * ``` - * @see {@link Entry} - * @see {@link KeyOf} - * @see {@link ReadonlyArrayLike} + * @see {@linkcode Entry} + * @see {@linkcode KeyOf} + * @see {@linkcode ReadonlyArrayLike} * @template Object Object to get the entry from. */ export type EntryOf = { readonly [ /** - * @see {@link EntryOf} property that shouldn't be referenced directly + * @see {@linkcode EntryOf} property that shouldn't be referenced directly */ Property in KeyOf ]: Entry< diff --git a/@coven/types/EntryValue.ts b/@coven/types/EntryValue.ts index 7eb4368..cb4855f 100644 --- a/@coven/types/EntryValue.ts +++ b/@coven/types/EntryValue.ts @@ -1,14 +1,16 @@ import type { Entry } from "./Entry.ts"; /** - * Value of an {@link Entry}. + * Value of an {@linkcode Entry}. * * @example * ```typescript + * import type { Entry } from "@coven/types"; + * * const entry = ["🧙‍♀️", 13] as const satisfies Entry; * const entryValue = entry[1] satisfies EntryValue; * ``` - * @see {@link Entry} + * @see {@linkcode Entry} * @template EntryTuple Entry to get the value from. */ export type EntryValue = EntryTuple[1]; diff --git a/@coven/types/Enumerate.ts b/@coven/types/Enumerate.ts index 324bf7c..f625e40 100644 --- a/@coven/types/Enumerate.ts +++ b/@coven/types/Enumerate.ts @@ -2,7 +2,9 @@ import type { IndexArray } from "./IndexArray.ts"; /** * Recursively generates a type with an union of numbers from `0` to `To`. - * This is expensive and has the same limit TypeScript has for recursive types. + * + * > [!IMPORTANT] + * > This is expensive and has the same limit TypeScript has for recursive types. * * @example * ```typescript diff --git a/@coven/types/Fallback.ts b/@coven/types/Fallback.ts index 80e2556..9f333c3 100644 --- a/@coven/types/Fallback.ts +++ b/@coven/types/Fallback.ts @@ -10,7 +10,7 @@ import type { Single } from "./Single.ts"; * type Test1 = Fallback; // number * type Test2 = Fallback; // string * ``` - * @see {@link Single} + * @see {@linkcode Single} * @template Wrong Type to avoid. * @template MaybeWrong Type to check. * @template FallbackType Fallback if `MaybeWrong` extends `Wrong`. diff --git a/@coven/types/Falsy.ts b/@coven/types/Falsy.ts index bcab00f..f392b9c 100644 --- a/@coven/types/Falsy.ts +++ b/@coven/types/Falsy.ts @@ -16,8 +16,8 @@ import type { Nullish } from "./Nullish.ts"; * const falsyZero = 0 as const satisfies Falsy; * const falsyZeroBigInt = 0n as const satisfies Falsy; * ``` - * @see {@link EmptyString} - * @see {@link Nullish} + * @see {@linkcode EmptyString} + * @see {@linkcode Nullish} * @see [Falsy](https://mdn.io/Falsy) */ export type Falsy = 0 | 0n | EmptyString | false | Nullish; diff --git a/@coven/types/Head.ts b/@coven/types/Head.ts index 3de95a4..628ea27 100644 --- a/@coven/types/Head.ts +++ b/@coven/types/Head.ts @@ -2,7 +2,7 @@ import type { HeadAndTail } from "./HeadAndTail.ts"; import type { ReadonlyArrayLike } from "./ReadonlyArrayLike.ts"; /** - * Initial value (item in index `0`) of a {@link ReadonlyArrayLike}. + * Initial value (item in index `0`) of a {@linkcode ReadonlyArrayLike}. * * @example * ```typescript @@ -12,8 +12,8 @@ import type { ReadonlyArrayLike } from "./ReadonlyArrayLike.ts"; * const emptyArray = [] as const; * const emptyHead = undefined satisfies Head; * ``` - * @see {@link HeadAndTail} - * @see {@link ReadonlyArrayLike} + * @see {@linkcode HeadAndTail} + * @see {@linkcode ReadonlyArrayLike} * @template ArrayLike `ReadonlyArrayLike` value (such as `Array` or `string`). */ export type Head = HeadAndTail< diff --git a/@coven/types/HeadAndTail.ts b/@coven/types/HeadAndTail.ts index f3306fb..f9a72a5 100644 --- a/@coven/types/HeadAndTail.ts +++ b/@coven/types/HeadAndTail.ts @@ -5,7 +5,7 @@ import type { ReadonlyArrayLike } from "./ReadonlyArrayLike.ts"; /** * Get a couple with the head (item at index `0`) and tail (all elements except - * index `0`) types of an {@link ReadonlyArrayLike}. + * index `0`) types of an {@linkcode ReadonlyArrayLike}. * * @example * ```typescript @@ -14,10 +14,10 @@ import type { ReadonlyArrayLike } from "./ReadonlyArrayLike.ts"; * typeof array * >; * ``` - * @see {@link EmptyArray} - * @see {@link EmptyString} - * @see {@link Maybe} - * @see {@link ReadonlyArrayLike} + * @see {@linkcode EmptyArray} + * @see {@linkcode EmptyString} + * @see {@linkcode Maybe} + * @see {@linkcode ReadonlyArrayLike} * @template ArrayLike `ReadonlyArrayLike` to get the head and tail. */ export type HeadAndTail = ArrayLike extends diff --git a/@coven/types/Hours.ts b/@coven/types/Hours.ts index 12431a7..9be45ed 100644 --- a/@coven/types/Hours.ts +++ b/@coven/types/Hours.ts @@ -7,7 +7,7 @@ import type { Enumerate } from "./Enumerate.ts"; * ```typescript * const hours = [0, 1, 2, 3, 20, 21, 22, 23] as const satisfies Iterable; * ``` - * @see {@link Enumerate} + * @see {@linkcode Enumerate} * @see [Date](https://mdn.io/Date) */ export type Hours = Enumerate<23>; diff --git a/@coven/types/ISODate.ts b/@coven/types/ISODate.ts index 4966409..a0ed60e 100644 --- a/@coven/types/ISODate.ts +++ b/@coven/types/ISODate.ts @@ -4,15 +4,15 @@ import type { MinimumLengthNumberString } from "./MinimumLengthNumberString.ts"; /** * [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format of a date (returned * by [Date#toISOString](https://mdn.io/Date.prototype.toISOString)). It uses - * {@link MinimumLengthNumberString} because the type complexity using better + * {@linkcode MinimumLengthNumberString} because the type complexity using better * types would be too hight (32,140,800,000 union types approximately). * * @example * ```typescript * const date = "2020-01-01T00:00:00.000Z" as const satisfies ISODate; * ``` - * @see {@link ISOYear} - * @see {@link MinimumLengthNumberString} + * @see {@linkcode ISOYear} + * @see {@linkcode MinimumLengthNumberString} * @see [Date](https://mdn.io/Date) * @see [Date#toISOString](https://mdn.io/Date.prototype.toISOString) * @see [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) diff --git a/@coven/types/ISODayOfMonth.ts b/@coven/types/ISODayOfMonth.ts index 93be0ce..0b8d261 100644 --- a/@coven/types/ISODayOfMonth.ts +++ b/@coven/types/ISODayOfMonth.ts @@ -7,7 +7,7 @@ import type { Digit } from "./Digit.ts"; * ```typescript * const days = ["01", "15", "31"] as const satisfies Iterable; * ``` - * @see {@link Digit} + * @see {@linkcode Digit} * @see [Date](https://mdn.io/Date) */ export type ISODayOfMonth = diff --git a/@coven/types/ISOHours.ts b/@coven/types/ISOHours.ts index 2727827..282752e 100644 --- a/@coven/types/ISOHours.ts +++ b/@coven/types/ISOHours.ts @@ -8,8 +8,8 @@ import type { Enumerate } from "./Enumerate.ts"; * ```typescript * const hours = ["00", "06", "23"] as const satisfies Iterable; * ``` - * @see {@link Digit} - * @see {@link Enumerate} + * @see {@linkcode Digit} + * @see {@linkcode Enumerate} * @see [Date](https://mdn.io/Date) */ export type ISOHours = `${0 | 1}${Digit}` | `2${Enumerate<3>}`; diff --git a/@coven/types/ISOMilliseconds.ts b/@coven/types/ISOMilliseconds.ts index aabb993..fa5ed39 100644 --- a/@coven/types/ISOMilliseconds.ts +++ b/@coven/types/ISOMilliseconds.ts @@ -11,7 +11,7 @@ import type { Digit } from "./Digit.ts"; * "999", * ] as const satisfies Iterable; * ``` - * @see {@link Digit} + * @see {@linkcode Digit} * @see [Date](https://mdn.io/Date) */ export type ISOMilliseconds = `${Digit}${Digit}${Digit}`; diff --git a/@coven/types/ISOMinutes.ts b/@coven/types/ISOMinutes.ts index b5f84df..27aedb2 100644 --- a/@coven/types/ISOMinutes.ts +++ b/@coven/types/ISOMinutes.ts @@ -8,8 +8,8 @@ import type { Enumerate } from "./Enumerate.ts"; * ```typescript * const minutes = ["00", "30", "59"] as const satisfies Iterable; * ``` - * @see {@link Digit} - * @see {@link Enumerate} + * @see {@linkcode Digit} + * @see {@linkcode Enumerate} * @see [Date](https://mdn.io/Date) */ export type ISOMinutes = `${Enumerate<5>}${Digit}`; diff --git a/@coven/types/ISOMonth.ts b/@coven/types/ISOMonth.ts index e8a904a..ba76ef9 100644 --- a/@coven/types/ISOMonth.ts +++ b/@coven/types/ISOMonth.ts @@ -8,8 +8,8 @@ import type { Enumerate } from "./Enumerate.ts"; * ```typescript * const months = ["01", "06", "12"] as const satisfies Iterable; * ``` - * @see {@link Digit} - * @see {@link Enumerate} + * @see {@linkcode Digit} + * @see {@linkcode Enumerate} * @see [Date](https://mdn.io/Date) */ export type ISOMonth = `0${Exclude}` | `1${Enumerate<2>}`; diff --git a/@coven/types/ISOSeconds.ts b/@coven/types/ISOSeconds.ts index bbe4687..f47a36d 100644 --- a/@coven/types/ISOSeconds.ts +++ b/@coven/types/ISOSeconds.ts @@ -8,8 +8,8 @@ import type { Enumerate } from "./Enumerate.ts"; * ```typescript * const seconds = ["00", "30", "59"] as const satisfies Iterable; * ``` - * @see {@link Digit} - * @see {@link Enumerate} + * @see {@linkcode Digit} + * @see {@linkcode Enumerate} * @see [Date](https://mdn.io/Date) */ export type ISOSeconds = `${Enumerate<5>}${Digit}`; diff --git a/@coven/types/ISOYear.ts b/@coven/types/ISOYear.ts index ddea78a..ccdd711 100644 --- a/@coven/types/ISOYear.ts +++ b/@coven/types/ISOYear.ts @@ -12,7 +12,7 @@ import type { MinimumLengthNumberString } from "./MinimumLengthNumberString.ts"; * "+001989", * ] as const satisfies Iterable; * ``` - * @see {@link MinimumLengthNumberString} + * @see {@linkcode MinimumLengthNumberString} * @see [Date](https://mdn.io/Date) */ export type ISOYear = diff --git a/@coven/types/IndexArray.ts b/@coven/types/IndexArray.ts index dc1cc03..9e4c29f 100644 --- a/@coven/types/IndexArray.ts +++ b/@coven/types/IndexArray.ts @@ -3,17 +3,19 @@ import type { ReadonlyArray } from "./ReadonlyArray.ts"; /** * Recursively generates an Array type with the given length. - * This is expensive and has the same limit TypeScript has for recursive types. + * + * > [!IMPORTANT] + * > This is expensive and has the same limit TypeScript has for recursive types. * * @example * ```typescript - * type Array10 = ArrayLength<10>; // [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] + * type Array10 = IndexArray<10>; // [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] * ``` - * @see {@link ReadonlyArray} + * @see {@linkcode ReadonlyArray} * @template Length Length of generated Array type. * @template _Accumulator **⚠️ INTERNAL:** Accumulator for the recursion. - * @see {@link EmptyArray} - * @see {@link ReadonlyArray} + * @see {@linkcode EmptyArray} + * @see {@linkcode ReadonlyArray} */ export type IndexArray< Length extends number = 0, diff --git a/@coven/types/Initial.ts b/@coven/types/Initial.ts index 3f76c6b..79a8fba 100644 --- a/@coven/types/Initial.ts +++ b/@coven/types/Initial.ts @@ -2,15 +2,15 @@ import type { InitialAndLast } from "./InitialAndLast.ts"; import type { ReadonlyArrayLike } from "./ReadonlyArrayLike.ts"; /** - * Initial values of an {@link ReadonlyArrayLike} (all items except the last). + * Initial values of an {@linkcode ReadonlyArrayLike} (all items except the last). * * @example * ```typescript * const array = ["🧙‍♀️", "🔮", "💀"] as const; * const initial = ["🧙‍♀️", "🔮"] as const satisfies Initial; * ``` - * @see {@link InitialAndLast} - * @see {@link ReadonlyArrayLike} + * @see {@linkcode InitialAndLast} + * @see {@linkcode ReadonlyArrayLike} * @template ArrayLike `ReadonlyArrayLike` value (such as `Array` or `string`). */ export type Initial = InitialAndLast< diff --git a/@coven/types/InitialAndLast.ts b/@coven/types/InitialAndLast.ts index ce07adf..7ffe16b 100644 --- a/@coven/types/InitialAndLast.ts +++ b/@coven/types/InitialAndLast.ts @@ -7,7 +7,7 @@ import type { ReadonlyArrayLike } from "./ReadonlyArrayLike.ts"; import type { UndefinedFallback } from "./UndefinedFallback.ts"; /** - * Get a couple with the initial and last types of an {@link ReadonlyArrayLike}. + * Get a couple with the initial and last types of an {@linkcode ReadonlyArrayLike}. * The first item has all elements except the last, and the second item has * the last element. * @@ -18,11 +18,11 @@ import type { UndefinedFallback } from "./UndefinedFallback.ts"; * typeof array * >; * ``` - * @see {@link EmptyArray} - * @see {@link EmptyString} - * @see {@link Head} - * @see {@link Maybe} - * @see {@link ReadonlyArrayLike} + * @see {@linkcode EmptyArray} + * @see {@linkcode EmptyString} + * @see {@linkcode Head} + * @see {@linkcode Maybe} + * @see {@linkcode ReadonlyArrayLike} * @template ArrayLike `ReadonlyArrayLike` to get the initial and last types. */ export type InitialAndLast = diff --git a/@coven/types/IsomorphicIteratorItem.ts b/@coven/types/IsomorphicIteratorItem.ts index 332977f..48762d9 100644 --- a/@coven/types/IsomorphicIteratorItem.ts +++ b/@coven/types/IsomorphicIteratorItem.ts @@ -1,15 +1,17 @@ import type { AwaitableIterator } from "./AwaitableIterator.ts"; /** - * Gets the type of the items in an {@link AwaitableIterator}. + * Gets the type of the items in an {@linkcode AwaitableIterator}. * * @example * ```typescript - * const iterator = [13, 42, 665] as const satisfies AwaitableIterator; + * import { AwaitableIterator } from "@coven/types"; + * + * const iterator = [13, 42, 665].values() satisfies AwaitableIterator; * * type Example = IteratorItem; // number * ``` - * @see {@link AwaitableIterator} + * @see {@linkcode AwaitableIterator} * @template Iterator `AwaitableIterator` to get the item type from. */ export type IteratorItem = Iterator extends diff --git a/@coven/types/IterableItem.ts b/@coven/types/IterableItem.ts index 6cec276..d70e606 100644 --- a/@coven/types/IterableItem.ts +++ b/@coven/types/IterableItem.ts @@ -1,14 +1,16 @@ import type { AwaitableIterable } from "./AwaitableIterable.ts"; /** - * Type of the items of an {@link AwaitableIterable}. + * Type of the items of an {@linkcode AwaitableIterable}. * * @example * ```typescript + * import { AwaitableIterable } from "@coven/types"; + * * const iterable = [13, 42, 665] as const satisfies AwaitableIterable; * const item = 13 as const satisfies IterableItem; * ``` - * @see {@link AwaitableIterable} + * @see {@linkcode AwaitableIterable} * @template Iterable `AwaitableIterable` type to get the item type from. */ export type IterableItem = Iterable extends diff --git a/@coven/types/IteratorItem.ts b/@coven/types/IteratorItem.ts index 6b6c139..db27501 100644 --- a/@coven/types/IteratorItem.ts +++ b/@coven/types/IteratorItem.ts @@ -1,15 +1,17 @@ import type { AwaitableIterator } from "./AwaitableIterator.ts"; /** - * Gets the type of the items in an {@link AwaitableIterator}. + * Gets the type of the items in an {@linkcode AwaitableIterator}. * * @example * ```typescript - * const iterator = [13, 42, 665] as const satisfies AwaitableIterator; + * import { AwaitableIterator } from "@coven/types"; + * + * const iterator = [13, 42, 665].values() satisfies AwaitableIterator; * * type Example = IteratorItem; // number * ``` - * @see {@link AwaitableIterator} + * @see {@linkcode AwaitableIterator} * @template Iterator AwaitableIterator to get the item type from. */ export type IteratorItem = Iterator extends diff --git a/@coven/types/JSONValue.ts b/@coven/types/JSONValue.ts index 18299dd..de5cc23 100644 --- a/@coven/types/JSONValue.ts +++ b/@coven/types/JSONValue.ts @@ -8,13 +8,13 @@ import type { Primitive } from "./Primitive.ts"; * ```typescript * const json = JSON.parse('{"🧙‍♀️": "🔮"}') satisfies JSONValue; * ``` - * @see {@link Primitive} + * @see {@linkcode Primitive} * @see [JSON](https://www.json.org/json-en.html) */ export type JSONValue = | { /** - * @see {@link JSONValue} untyped property. + * @see {@linkcode JSONValue} untyped property. */ readonly [property: string]: JSONValue; } diff --git a/@coven/types/Just.ts b/@coven/types/Just.ts index 9b56b27..15dfd0f 100644 --- a/@coven/types/Just.ts +++ b/@coven/types/Just.ts @@ -4,9 +4,10 @@ * * @example * ```typescript + * import type { Maybe } from "@coven/types"; + * * const maybeUndefined = "🧙‍♀️" as Maybe; - * const defined = "🧙‍♀️" as const satisfies Just; // ok - * const noDefined = undefined satisfies Just; // error + * const defined = "🧙‍♀️" as const satisfies Just; * ``` * @template MaybeUndefined Type to exclude `undefined` from. */ diff --git a/@coven/types/KeyOf.ts b/@coven/types/KeyOf.ts index 3289a2f..da3c308 100644 --- a/@coven/types/KeyOf.ts +++ b/@coven/types/KeyOf.ts @@ -9,11 +9,11 @@ import type { ReadonlyArrayLike } from "./ReadonlyArrayLike.ts"; * const array = [13, 42] as const; * const object = { "🧙‍♀️": "🔮" } as const; * - * const arrayKey = 0 as const satisfies KeyOf; + * const arrayKey = "0" as const satisfies KeyOf; * const objectKey = "🧙‍♀️" as const satisfies KeyOf; * ``` - * @see {@link ArrayLikeIndexFallback} - * @see {@link ReadonlyArrayLike} + * @see {@linkcode ArrayLikeIndexFallback} + * @see {@linkcode ReadonlyArrayLike} * @template Object Object type to get the key from. */ export type KeyOf = `${Object extends ReadonlyArrayLike diff --git a/@coven/types/LanguageTag.ts b/@coven/types/LanguageTag.ts index dc77bf4..b95cb17 100644 --- a/@coven/types/LanguageTag.ts +++ b/@coven/types/LanguageTag.ts @@ -8,7 +8,7 @@ import type { LanguageCode } from "./LanguageCode.ts"; * ```typescript * const locale = "en-US" as const satisfies LanguageTag; * ``` - * @see {@link LanguageCode} + * @see {@linkcode LanguageCode} * @see [ISO 639](https://en.wikipedia.org/wiki/IETF_language_tag) * @see [IETF BCP 47](https://en.wikipedia.org/wiki/ISO_639) */ diff --git a/@coven/types/Last.ts b/@coven/types/Last.ts index ce5fdfb..8e20004 100644 --- a/@coven/types/Last.ts +++ b/@coven/types/Last.ts @@ -2,15 +2,15 @@ import type { InitialAndLast } from "./InitialAndLast.ts"; import type { ReadonlyArrayLike } from "./ReadonlyArrayLike.ts"; /** - * Last item of an {@link ReadonlyArrayLike}. + * Last item of an {@linkcode ReadonlyArrayLike}. * * @example * ```typescript * const array = ["🧙‍♀️", "🔮", "💀"] as const; * const last = "💀" as const satisfies Last; * ``` - * @see {@link InitialAndLast} - * @see {@link ReadonlyArrayLike} + * @see {@linkcode InitialAndLast} + * @see {@linkcode ReadonlyArrayLike} * @template ArrayLike `ReadonlyArrayLike` to get the last item from. */ export type Last = InitialAndLast< diff --git a/@coven/types/Maybe.ts b/@coven/types/Maybe.ts index 53f283e..eb32a54 100644 --- a/@coven/types/Maybe.ts +++ b/@coven/types/Maybe.ts @@ -11,8 +11,8 @@ import type { Just } from "./Just.ts"; * const maybeNumber = 1 as const satisfies MaybeNumber; * const notNumber = undefined satisfies MaybeNumber; * ``` - * @see {@link Either} - * @see {@link Just} + * @see {@linkcode Either} + * @see {@linkcode Just} * @template OptionalType The type of the value to make optional. */ export type Maybe = Either, undefined>; diff --git a/@coven/types/Milliseconds.ts b/@coven/types/Milliseconds.ts index d6f5d5e..20a68a5 100644 --- a/@coven/types/Milliseconds.ts +++ b/@coven/types/Milliseconds.ts @@ -7,7 +7,7 @@ import type { Enumerate } from "./Enumerate.ts"; * ```typescript * const milliseconds = [1, 250, 999] as const satisfies Iterable; * ``` - * @see {@link Enumerate} + * @see {@linkcode Enumerate} * @see [Date](https://mdn.io/Date) */ export type Milliseconds = Enumerate<999>; diff --git a/@coven/types/MinimumLengthNumberString.ts b/@coven/types/MinimumLengthNumberString.ts index d470698..ca9b3dd 100644 --- a/@coven/types/MinimumLengthNumberString.ts +++ b/@coven/types/MinimumLengthNumberString.ts @@ -9,13 +9,13 @@ import type { ReadonlyArray } from "./ReadonlyArray.ts"; * * @example * ```typescript - * const test1 = "1" as const satisfies MultiDigitNumberString<1>; // ok - * const test2 = "01" as const satisfies MultiDigitNumberString<2>; // ok - * const test3 = "1" as const satisfies MultiDigitNumberString<3>; // error + * const test1 = "1" as const satisfies MinimumLengthNumberString<1>; + * const test2 = "01" as const satisfies MinimumLengthNumberString<2>; + * const test3 = "012" as const satisfies MinimumLengthNumberString<3>; * ``` - * @see {@link Digit} - * @see {@link EmptyString} - * @see {@link ReadonlyArray} + * @see {@linkcode Digit} + * @see {@linkcode EmptyString} + * @see {@linkcode ReadonlyArray} * @template MinimumLength Minimum length for the number string. * @template _Accumulator **⚠️ INTERNAL:** Output accumulator. * @template _Tracker **⚠️ INTERNAL:** Loop tracking accumulator. diff --git a/@coven/types/Minutes.ts b/@coven/types/Minutes.ts index 9f42d41..277f687 100644 --- a/@coven/types/Minutes.ts +++ b/@coven/types/Minutes.ts @@ -7,7 +7,7 @@ import type { Enumerate } from "./Enumerate.ts"; * ```typescript * const minutes = [0, 30, 59] as const satisfies Iterable; * ``` - * @see {@link Enumerate} + * @see {@linkcode Enumerate} * @see [Date](https://mdn.io/Date) */ export type Minutes = Enumerate<59>; diff --git a/@coven/types/Month.ts b/@coven/types/Month.ts index 86d0a6a..4ff6e89 100644 --- a/@coven/types/Month.ts +++ b/@coven/types/Month.ts @@ -5,9 +5,9 @@ import type { Enumerate } from "./Enumerate.ts"; * * @example * ```typescript - * const months = [1, 6, 11] as const satisfies Iterable; + * const months = [1, 6, 11] as const satisfies Iterable; * ``` - * @see {@link Enumerate} + * @see {@linkcode Enumerate} * @see [Date](https://mdn.io/Date) */ export type Month = Enumerate<11>; diff --git a/@coven/types/NeverFallback.ts b/@coven/types/NeverFallback.ts index d5e5719..b701241 100644 --- a/@coven/types/NeverFallback.ts +++ b/@coven/types/NeverFallback.ts @@ -10,7 +10,7 @@ import type { Fallback } from "./Fallback.ts"; * type Type1 = NeverFallback; // number * type Type2 = NeverFallback; // string * ``` - * @see {@link Fallback} + * @see {@linkcode Fallback} * @template MaybeNever The type that may or may not be `never`. * @template FallbackType The fallback type to use if `MaybeNever` is `never`. */ diff --git a/@coven/types/Nullish.ts b/@coven/types/Nullish.ts index 1989663..752957c 100644 --- a/@coven/types/Nullish.ts +++ b/@coven/types/Nullish.ts @@ -8,7 +8,7 @@ import type { Maybe } from "./Maybe.ts"; * const nullishUndefined = undefined satisfies Nullish; * const nullishNull = null satisfies Nullish; * ``` - * @see {@link Maybe} + * @see {@linkcode Maybe} * @see [Nullish](https://mdn.io/Nullish%20value) */ export type Nullish = Maybe; diff --git a/@coven/types/Primitive.ts b/@coven/types/Primitive.ts index de46d21..4b11d5d 100644 --- a/@coven/types/Primitive.ts +++ b/@coven/types/Primitive.ts @@ -14,8 +14,8 @@ import type { Numeric } from "./Numeric.ts"; * const aString = "🧙‍♀️" as const satisfies Primitive; * const aSymbol = Symbol("🧙‍♀️") satisfies Primitive; * ``` - * @see {@link Nullish} - * @see {@link Numeric} + * @see {@linkcode Nullish} + * @see {@linkcode Numeric} * @see [Primitive](https://mdn.io/Primitive) */ export type Primitive = boolean | Nullish | Numeric | string | symbol; diff --git a/@coven/types/README.md b/@coven/types/README.md index 371dc05..6557545 100644 --- a/@coven/types/README.md +++ b/@coven/types/README.md @@ -3,8 +3,7 @@ [![JSR](https://jsr.io/badges/@coven/types)](https://jsr.io/@coven/types) [![JSR Score](https://jsr.io/badges/@coven/types/score)](https://jsr.io/@coven/types/score) -📚 Arcane types codex used across [Coven Engineering](https://coven.engineering) -libraries. +🏷️ Collection of TypeScript types. ## Example diff --git a/@coven/types/Radix.ts b/@coven/types/Radix.ts index f94056f..68b65c9 100644 --- a/@coven/types/Radix.ts +++ b/@coven/types/Radix.ts @@ -10,6 +10,6 @@ import type { Range } from "./Range.ts"; * const decimal = 10 as const satisfies Radix; * const hexadecimal = 0x10 as const satisfies Radix; * ``` - * @see {@link Range} + * @see {@linkcode Range} */ export type Radix = Range<2, 36>; diff --git a/@coven/types/Range.ts b/@coven/types/Range.ts index 823c6d5..d53a0d8 100644 --- a/@coven/types/Range.ts +++ b/@coven/types/Range.ts @@ -2,15 +2,15 @@ import type { Enumerate } from "./Enumerate.ts"; import type { NeverFallback } from "./NeverFallback.ts"; /** - * Generates a range of numbers using {@link Enumerate} from `From` to `To`. + * Generates a range of numbers using {@linkcode Enumerate} from `From` to `To`. * * @example * ```typescript * type From5To10 = Range<5, 10>; // 5 | 6 | 7 | 8 | 9 | 10 * type From5To10Alternative = Range<10, 5>; // 5 | 6 | 7 | 8 | 9 | 10 * ``` - * @see {@link Enumerate} - * @see {@link NeverFallback} + * @see {@linkcode Enumerate} + * @see {@linkcode NeverFallback} * @template From Origin value (inclusive). * @template To Last value (inclusive). */ diff --git a/@coven/types/ReadonlyArray.ts b/@coven/types/ReadonlyArray.ts index 247f515..865cb95 100644 --- a/@coven/types/ReadonlyArray.ts +++ b/@coven/types/ReadonlyArray.ts @@ -8,7 +8,6 @@ * const array = [{ "🧙‍♀️": 13 }, { "🧙‍♀️": 42 }] as const satisfies ReadonlyArray<{ * "🧙‍♀️": number; * }>; - * array.push("oops"); // Error * array[0]; // Maybe<{ "🧙‍♀️": number }> * ``` * diff --git a/@coven/types/ReadonlyArrayLike.ts b/@coven/types/ReadonlyArrayLike.ts index 1cbd7dd..c186970 100644 --- a/@coven/types/ReadonlyArrayLike.ts +++ b/@coven/types/ReadonlyArrayLike.ts @@ -20,11 +20,11 @@ import type { Single } from "./Single.ts"; * 3 * >; * ``` - * @see {@link Enumerate} - * @see {@link Maybe} - * @see {@link NeverFallback} - * @see {@link ReadonlyRecord} - * @see {@link Single} + * @see {@linkcode Enumerate} + * @see {@linkcode Maybe} + * @see {@linkcode NeverFallback} + * @see {@linkcode ReadonlyRecord} + * @see {@linkcode Single} * @template Item Type of the items in the array-like object. * @template Length Length value of the array-like object. */ @@ -34,7 +34,7 @@ export type ReadonlyArrayLike< > = & { /** - * Amount of items in the {@link ReadonlyArrayLike}. + * Amount of items in the {@linkcode ReadonlyArrayLike}. */ readonly length: Length; } diff --git a/@coven/types/Replace.ts b/@coven/types/Replace.ts index 3e22ed7..e1a5808 100644 --- a/@coven/types/Replace.ts +++ b/@coven/types/Replace.ts @@ -9,7 +9,7 @@ import type { ReadonlyRecord } from "./ReadonlyRecord.ts"; * type User = { readonly name: string; readonly age: number }; * type ReallyOldUser = Replace; * ``` - * @see {@link ReadonlyRecord} + * @see {@linkcode ReadonlyRecord} * @template Original Type to replace the type of some keys in. * @template Replacements Property name to type dictionary of replacements. */ diff --git a/@coven/types/Seconds.ts b/@coven/types/Seconds.ts index 97f21e6..d015865 100644 --- a/@coven/types/Seconds.ts +++ b/@coven/types/Seconds.ts @@ -7,7 +7,7 @@ import type { Enumerate } from "./Enumerate.ts"; * ```typescript * const seconds = [0, 30, 59] as const satisfies Iterable; * ``` - * @see {@link Enumerate} + * @see {@linkcode Enumerate} * @see [Date](https://mdn.io/Date) */ export type Seconds = Enumerate<59>; diff --git a/@coven/types/StringJoin.ts b/@coven/types/StringJoin.ts index 61beccb..f2799ea 100644 --- a/@coven/types/StringJoin.ts +++ b/@coven/types/StringJoin.ts @@ -11,9 +11,9 @@ import type { Stringable } from "./Stringable.ts"; * ```typescript * type CovenEngineering = StringJoin; // "Coven Engineering" * ``` - * @see {@link EmptyString} - * @see {@link ReadonlyArray} - * @see {@link Stringable} + * @see {@linkcode EmptyString} + * @see {@linkcode ReadonlyArray} + * @see {@linkcode Stringable} * @template StringableArray Array to join. * @template Glue String to use to glue items together. * @template _Accumulator **⚠️ INTERNAL:** Output accumulator. diff --git a/@coven/types/Stringable.ts b/@coven/types/Stringable.ts index fdbccc6..b41f9f3 100644 --- a/@coven/types/Stringable.ts +++ b/@coven/types/Stringable.ts @@ -5,12 +5,10 @@ import type { Primitive } from "./Primitive.ts"; * * @example * ```typescript - * let value = "hello" as const satisfies Stringable; - * value = 1; - * value = true; - * value = Symbol("hello"); // Error! - * value = { toString: () => "hello" }; // Error! + * const string = "hello" as const satisfies Stringable; + * const number = 1 as const satisfies Stringable; + * const boolean = true as const satisfies Stringable; * ``` - * @see {@link Primitive} + * @see {@linkcode Primitive} */ export type Stringable = Exclude; diff --git a/@coven/types/StructuredData.ts b/@coven/types/StructuredData.ts index e602daa..19fd0eb 100644 --- a/@coven/types/StructuredData.ts +++ b/@coven/types/StructuredData.ts @@ -7,13 +7,13 @@ import type { Primitive } from "./Primitive.ts"; * ```typescript * const clone = structuredClone({} satisfies StructuredData); * ``` - * @see {@link Primitive} + * @see {@linkcode Primitive} * @see [structuredClone](https://mdn.io/structuredClone) */ export type StructuredData = | { /** - * @see {@link StructuredData} untyped property. + * @see {@linkcode StructuredData} untyped property. */ readonly [property: string]: StructuredData; } diff --git a/@coven/types/Tagger.ts b/@coven/types/Tagger.ts index 7d57937..cc2d3b0 100644 --- a/@coven/types/Tagger.ts +++ b/@coven/types/Tagger.ts @@ -10,7 +10,7 @@ import type { ReadonlyTemplateStringsArray } from "./ReadonlyTemplateStringsArra * parseInt(strings.join(""), 16)) satisfies Tagger; * hexParser`f`; // 15 * ``` - * @see {@link ReadonlyArray} + * @see {@linkcode ReadonlyArray} * @see [Template Literals](https://mdn.io/Template%20literals) * @template Output Type of the output value. * @template Expressions Type of the expressions. diff --git a/@coven/types/Tail.ts b/@coven/types/Tail.ts index bbb892a..1b96e27 100644 --- a/@coven/types/Tail.ts +++ b/@coven/types/Tail.ts @@ -2,18 +2,18 @@ import type { HeadAndTail } from "./HeadAndTail.ts"; import type { ReadonlyArrayLike } from "./ReadonlyArrayLike.ts"; /** - * All items of a {@link ReadonlyArrayLike} except the last. + * All items of a {@linkcode ReadonlyArrayLike} except the last. * * @example * ```typescript * const array = ["🧙‍♀️", "🔮", "💀"] as const; * const tail = ["🔮", "💀"] as const satisfies Tail; * - * const emptyArray = []; + * const emptyArray = [] as const; * const emptyTail = undefined satisfies Tail; * ``` - * @see {@link HeadAndTail} - * @see {@link ReadonlyArrayLike} + * @see {@linkcode HeadAndTail} + * @see {@linkcode ReadonlyArrayLike} * @template ArrayLike Type of the array to get the tail. */ export type Tail = HeadAndTail< diff --git a/@coven/types/TypeOfDictionary.ts b/@coven/types/TypeOfDictionary.ts index 6cc5f97..d45dbbe 100644 --- a/@coven/types/TypeOfDictionary.ts +++ b/@coven/types/TypeOfDictionary.ts @@ -4,58 +4,58 @@ * * @example * ```typescript - * type TypeOfString = TypeOfMap["string"]; // `string` - * type TypeOfBoolean = TypeOfMap["boolean"]; // `boolean` - * type TypeOfFunction = TypeOfMap["function"]; // `Function` - * type TypeOfNull = TypeOfMap["null"]; // `null` + * type TypeOfString = TypeOfDictionary["string"]; // `string` + * type TypeOfBoolean = TypeOfDictionary["boolean"]; // `boolean` + * type TypeOfFunction = TypeOfDictionary["function"]; // `Function` + * type TypeOfNull = TypeOfDictionary["null"]; // `null` * ``` * @see [typeof null bug](https://lou.cx/null-bug) * @see [typeof typeof rejected proposal](https://lou.cx/null-typeof) */ export type TypeOfDictionary = { /** - * {@link TypeOfDictionary} key for `BigInt`. + * {@linkcode TypeOfDictionary} key for `BigInt`. */ readonly bigint: bigint; /** - * {@link TypeOfDictionary} key for `Boolean`. + * {@linkcode TypeOfDictionary} key for `Boolean`. */ readonly boolean: boolean; /** - * {@link TypeOfDictionary} key for `Function`. + * {@linkcode TypeOfDictionary} key for `Function`. */ // deno-lint-ignore ban-types readonly function: Function; /** - * {@link TypeOfDictionary} key for `null`. + * {@linkcode TypeOfDictionary} key for `null`. */ readonly null: null; /** - * {@link TypeOfDictionary} key for `Number`. + * {@linkcode TypeOfDictionary} key for `Number`. */ readonly number: number; /** - * {@link TypeOfDictionary} key for `Object`. + * {@linkcode TypeOfDictionary} key for `Object`. */ readonly object: object; /** - * {@link TypeOfDictionary} key for `String`. + * {@linkcode TypeOfDictionary} key for `String`. */ readonly string: string; /** - * {@link TypeOfDictionary} key for `Symbol`. + * {@linkcode TypeOfDictionary} key for `Symbol`. */ readonly symbol: symbol; /** - * {@link TypeOfDictionary} key for `undefined`. + * {@linkcode TypeOfDictionary} key for `undefined`. */ readonly undefined: undefined; }; diff --git a/@coven/types/TypeOfValue.ts b/@coven/types/TypeOfValue.ts index f10a0a7..7b07574 100644 --- a/@coven/types/TypeOfValue.ts +++ b/@coven/types/TypeOfValue.ts @@ -11,8 +11,8 @@ import type { TypeOfDictionary } from "./TypeOfDictionary.ts"; * const typeBoolean = "boolean" as const satisfies TypeOfValue; * const typeFunction = "function" as const satisfies TypeOfValue; * ``` - * @see {@link KeyOf} - * @see {@link TypeOfDictionary} + * @see {@linkcode KeyOf} + * @see {@linkcode TypeOfDictionary} * @see [typeof null bug](https://lou.cx/null-bug) * @see [typeof typeof rejected proposal](https://lou.cx/null-typeof) */ diff --git a/@coven/types/UndefinedFallback.ts b/@coven/types/UndefinedFallback.ts index c40e909..0b20d54 100644 --- a/@coven/types/UndefinedFallback.ts +++ b/@coven/types/UndefinedFallback.ts @@ -10,8 +10,8 @@ import type { Just } from "./Just.ts"; * type Type1 = UndefinedFallback; // number * type Type2 = UndefinedFallback; // string * ``` - * @see {@link Fallback} - * @see {@link Just} + * @see {@linkcode Fallback} + * @see {@linkcode Just} * @template MaybeUndefined The type that may or may not be `undefined`. * @template FallbackType The fallback type to use if `MaybeUndefined` is `undefined`. */ diff --git a/@coven/types/ValueOf.ts b/@coven/types/ValueOf.ts index 92e4f2c..1f9f841 100644 --- a/@coven/types/ValueOf.ts +++ b/@coven/types/ValueOf.ts @@ -2,7 +2,7 @@ import type { ReadonlyArrayLike } from "./ReadonlyArrayLike.ts"; /** * Type of property values in an object (also works for items in an - * {@link ReadonlyArrayLike}). + * {@linkcode ReadonlyArrayLike}). * * @example * ```typescript @@ -12,7 +12,7 @@ import type { ReadonlyArrayLike } from "./ReadonlyArrayLike.ts"; * } as const; * const key = 13 as const satisfies ValueOf; * ``` - * @see {@link ReadonlyArrayLike} + * @see {@linkcode ReadonlyArrayLike} * @template Object Object or array type. */ export type ValueOf = Object extends ReadonlyArrayLike diff --git a/@coven/types/deno.json b/@coven/types/deno.json index a46ddab..f854ed5 100644 --- a/@coven/types/deno.json +++ b/@coven/types/deno.json @@ -1,5 +1,5 @@ { "name": "@coven/types", - "version": "0.0.11", + "version": "0.3.0", "exports": "./mod.ts" } diff --git a/@coven/types/mod.ts b/@coven/types/mod.ts index e9e0802..151a834 100644 --- a/@coven/types/mod.ts +++ b/@coven/types/mod.ts @@ -1,6 +1,7 @@ export type { Add } from "./Add.ts"; export type { ArrayLikeIndexFallback } from "./ArrayLikeIndexFallback.ts"; export type { Awaitable } from "./Awaitable.ts"; +export type { AwaitableEffect } from "./AwaitableEffect.ts"; export type { AwaitableGenerator } from "./AwaitableGenerator.ts"; export type { AwaitableIterable } from "./AwaitableIterable.ts"; export type { AwaitableIterableIterator } from "./AwaitableIterableIterator.ts"; @@ -9,6 +10,7 @@ export type { Class } from "./Class.ts"; export type { DayOfMonth } from "./DayOfMonth.ts"; export type { DayOfWeek } from "./DayOfWeek.ts"; export type { Digit } from "./Digit.ts"; +export type { Effect } from "./Effect.ts"; export type { Either } from "./Either.ts"; export type { EmptyArray } from "./EmptyArray.ts"; export type { EmptyString } from "./EmptyString.ts"; diff --git a/@coven/utils/README.md b/@coven/utils/README.md index 43dd89d..e89a444 100644 --- a/@coven/utils/README.md +++ b/@coven/utils/README.md @@ -3,7 +3,7 @@ [![JSR](https://jsr.io/badges/@coven/utils)](https://jsr.io/@coven/utils) [![JSR Score](https://jsr.io/badges/@coven/utils/score)](https://jsr.io/@coven/utils/score) -🪄 Utility spells. +🛠️ General utilities. ## Example diff --git a/@coven/utils/always.ts b/@coven/utils/always.ts index 1ebc76c..4b171c3 100644 --- a/@coven/utils/always.ts +++ b/@coven/utils/always.ts @@ -7,9 +7,8 @@ import { thunk } from "./thunk.ts"; * @example * ```typescript * const alwaysFoo = always("foo"); - * const fillWithFoo = map(alwaysFoo); * - * fillWithFoo([0, 1, 2]); // ["foo", "foo", "foo"] + * [0, 1, 2].map(alwaysFoo); // ["foo", "foo", "foo"] * ``` * @returns Function that always return the given value. */ diff --git a/@coven/utils/cryptoNumber.ts b/@coven/utils/cryptoNumber.ts index b343ca7..07b447f 100644 --- a/@coven/utils/cryptoNumber.ts +++ b/@coven/utils/cryptoNumber.ts @@ -1,3 +1,5 @@ +import type { Stringable } from "@coven/types"; + const textEncoder = new TextEncoder(); const LITTLE_ENDIAN = true; const sha256ToNumber = (sha256: ArrayBuffer) => @@ -11,8 +13,8 @@ const sha256ToNumber = (sha256: ArrayBuffer) => * * @example * ```typescript - * const seededRandom1 = await random("some seed"); - * const seededRandom2 = await random("some seed"); + * const seededRandom1 = await cryptoNumber("some seed"); + * const seededRandom2 = await cryptoNumber("some seed"); * * seededRandom1 === seededRandom2; // true because it has the same seed * ``` @@ -20,7 +22,7 @@ const sha256ToNumber = (sha256: ArrayBuffer) => * @param seed Seed to be used to generate random numbers. * @returns Pseudo-random number from seed. */ -export const cryptoNumber = (seed: string): Promise => +export const cryptoNumber = (seed: Stringable): Promise => crypto.subtle - .digest("SHA-256", textEncoder.encode(seed)) + .digest("SHA-256", textEncoder.encode(`${seed}`)) .then(sha256ToNumber); diff --git a/@coven/utils/deno.json b/@coven/utils/deno.json index 09c8f23..0cc5398 100644 --- a/@coven/utils/deno.json +++ b/@coven/utils/deno.json @@ -1,5 +1,5 @@ { "name": "@coven/utils", - "version": "0.0.9", + "version": "0.3.0", "exports": "./mod.ts" } diff --git a/@coven/utils/get.ts b/@coven/utils/get.ts index 570007b..fab29a6 100644 --- a/@coven/utils/get.ts +++ b/@coven/utils/get.ts @@ -5,10 +5,9 @@ import type { ReadonlyRecord } from "@coven/types"; * * @example * ```typescript - * const getFoo = get("foo"); + * const getWitch = get("witch"); * - * getFoo({ foo: "bar" }); // "bar" - * getFoo({}); // undefined + * getWitch({ witch: "🧙🏻‍♀️" }); // "🧙🏻‍♀️" * ``` * @returns Curried function with `key` in context. */ diff --git a/@coven/utils/mutate.ts b/@coven/utils/mutate.ts index aaecfc8..5c4b6aa 100644 --- a/@coven/utils/mutate.ts +++ b/@coven/utils/mutate.ts @@ -3,6 +3,8 @@ * * @example * ```typescript + * import { set } from "@coven/utils"; + * * const state = { a: 1 }; * mutate(set("a")(2))(state); * console.log(state); // { a: 2 } diff --git a/@coven/utils/tap.ts b/@coven/utils/tap.ts index b4799a9..611e323 100644 --- a/@coven/utils/tap.ts +++ b/@coven/utils/tap.ts @@ -1,4 +1,4 @@ -import type { Unary } from "@coven/types"; +import type { Effect, Unary } from "@coven/types"; /** * Tap into a value before calling a function. @@ -16,7 +16,7 @@ import type { Unary } from "@coven/types"; */ export const tap = ( tapper: Unary<[input: Input], Output>, -): >( +): >( tapped: Tapped, ) => Unary<[input: Input], Output> => (tapped) => diff --git a/@coven/utils/thunk.ts b/@coven/utils/thunk.ts index 9928bc9..488a1dd 100644 --- a/@coven/utils/thunk.ts +++ b/@coven/utils/thunk.ts @@ -5,7 +5,9 @@ import type { Unary } from "@coven/types"; * * @example * ```typescript - * const always = thunk(id); + * import { identity } from "@coven/utils"; + * + * const always = thunk(identity); * const alwaysFoo = always("foo") * alwaysFoo(); // "foo" * ``` diff --git a/@simulcast/core/Emitter.ts b/@simulcast/core/Emitter.ts index edfc0a3..6594b84 100644 --- a/@simulcast/core/Emitter.ts +++ b/@simulcast/core/Emitter.ts @@ -1,9 +1,10 @@ -import type { Single, Unary } from "@coven/types"; +import type { Effect, Single } from "@coven/types"; /** * Emitter function (when data is `never` it doesn't take any arguments). * * @template Data Data type. */ -export type Emitter = Single extends Single ? () => void - : Unary<[data: Data], void>; +export type Emitter = Effect< + Single extends Single ? [] : [data: Data] +>; diff --git a/@simulcast/core/EventListener.ts b/@simulcast/core/EventListener.ts index be62b4c..cd49604 100644 --- a/@simulcast/core/EventListener.ts +++ b/@simulcast/core/EventListener.ts @@ -1,11 +1,11 @@ -import type { Single, Unary } from "@coven/types"; +import type { Effect, Single } from "@coven/types"; /** * Event listener unary function. * * @template Data Data type. - * @see [Unary](https://jsr.io/@coven/types@0.0.11/doc/~/Unary) + * @see [Unary](https://jsr.io/@coven/types/doc/~/Unary) */ export type EventListener = Single extends Single ? () => void - : Unary<[data: Data], void>; + : Effect<[data: Data]>; diff --git a/@simulcast/core/EventRegistry.ts b/@simulcast/core/EventRegistry.ts index 30a23f4..84bb975 100644 --- a/@simulcast/core/EventRegistry.ts +++ b/@simulcast/core/EventRegistry.ts @@ -4,12 +4,12 @@ import type { EventTypeDictionary } from "./EventTypeDictionary.ts"; /** * Registry of event names to array of listeners. * - * @see {@link EventListener} - * @see {@link EventTypeDictionary} + * @see {@linkcode EventListener} + * @see {@linkcode EventTypeDictionary} * @example * ```typescript - * const eventRegistry = { - * example: [() => console.log("example called")], + * const eventRegistry: EventRegistry<{ example: never }> = { + * example: [() => console.log("example called")].values(), * }; * ``` * @template Events Event registry. diff --git a/@simulcast/core/EventTypeDictionary.ts b/@simulcast/core/EventTypeDictionary.ts index 104b94c..90251df 100644 --- a/@simulcast/core/EventTypeDictionary.ts +++ b/@simulcast/core/EventTypeDictionary.ts @@ -3,12 +3,6 @@ import type { ReadonlyRecord } from "@coven/types"; /** * Dictionary of event name to event types. * - * @example - * ```typescript - * const example = { - * eventName: TypeOfEvent, - * } satisfies EventTypeDictionary; - * ``` - * @see [ReadonlyRecord](https://jsr.io/@coven/types@0.0.11/doc/~/ReadonlyRecord) + * @see [ReadonlyRecord](https://jsr.io/@coven/types/doc/~/ReadonlyRecord) */ export type EventTypeDictionary = ReadonlyRecord; diff --git a/@simulcast/core/README.md b/@simulcast/core/README.md index b85358a..2a33431 100644 --- a/@simulcast/core/README.md +++ b/@simulcast/core/README.md @@ -3,7 +3,7 @@ [![JSR](https://jsr.io/badges/@simulcast/core)](https://jsr.io/@simulcast/core) [![JSR Score](https://jsr.io/badges/@simulcast/core/score)](https://jsr.io/@simulcast/core/score) -🔮 Communicate across frameworks like magic. +📡 Cross-framework communication. This library is an extremely minimal pub-sub implementation that uses iterables to make the dispatched events as responsive as possible for users. diff --git a/@simulcast/core/deno.json b/@simulcast/core/deno.json index 6d25697..50c16b2 100644 --- a/@simulcast/core/deno.json +++ b/@simulcast/core/deno.json @@ -1,5 +1,5 @@ { "name": "@simulcast/core", - "version": "0.1.0", + "version": "0.3.0", "exports": "./mod.ts" } diff --git a/@simulcast/core/emit.ts b/@simulcast/core/emit.ts index 3ed9693..3c28af9 100644 --- a/@simulcast/core/emit.ts +++ b/@simulcast/core/emit.ts @@ -14,7 +14,7 @@ import type { EventTypeDictionary } from "./EventTypeDictionary.ts"; * @example * ```typescript * const eventRegistry = {}; - * const emitRegistry = emit(eventRegistry); // 👈🏻 You are here + * const emitRegistry = emit(eventRegistry); * const emitEvent = emitRegistry("event"); * emitEvent("data"); * ``` @@ -25,20 +25,6 @@ import type { EventTypeDictionary } from "./EventTypeDictionary.ts"; export const emit = ( eventRegistry: EventRegistry, ): (event: Event) => Emitter => -/** - * Creates a curried function to emit an event of the `eventRegistry` in context. - * - * @example - * ```typescript - * const eventRegistry = {}; - * const emitRegistry = emit(eventRegistry); - * const emitEvent = emitRegistry("event"); // 👈🏻 You are here - * emitEvent("data"); - * ``` - * @template Event Event name. - * @param event Event name (has to be a valid key of the `eventRegistry`). - * @returns Curried function with `eventRegistry` and `event` in context. - */ (event: Event) => { const getEvent = get(event) as ( eventRegistry: EventRegistry, diff --git a/@simulcast/core/on.ts b/@simulcast/core/on.ts index 33dcefd..b2a92cb 100644 --- a/@simulcast/core/on.ts +++ b/@simulcast/core/on.ts @@ -12,13 +12,18 @@ import type { EventTypeDictionary } from "./EventTypeDictionary.ts"; * * @example * ```typescript - * const eventRegistry = {}; - * const onRegistry = on(eventRegistry); // 👈🏻 You are here - * const onEvent = onRegistry("event"); - * const offEvent = onEvent(() => console.log("event called")); - * emit(eventRegistry)("event")(); // Logs "event called" + * import { emit, type EventRegistry } from "@simulcast/core"; + * + * const exampleEvent = "example"; + * const eventRegistry: EventRegistry<{ [exampleEvent]: string }> = {}; + * const onRegistry = on(eventRegistry); + * const emitRegistry = emit(eventRegistry); + * const onEvent = onRegistry(exampleEvent); + * const emitEvent = emitRegistry(exampleEvent); + * const offEvent = onEvent(console.log); + * emitEvent("Will log"); * offEvent(); - * emit(eventRegistry)("event")(); // Nothing happens + * emitEvent("Will not log"); * ``` * @template Events Event registry. * @param eventRegistry Record of event names mapped to an array of listeners. diff --git a/TODO.md b/TODO.md index 756e908..2afd1d4 100644 --- a/TODO.md +++ b/TODO.md @@ -13,8 +13,8 @@ to `1.0.0` for everything. Now about the actual "to do": - [x] Move `@lou.codes/notify` as `@simulcast/core`. - [x] Move `*-pair` as `@coven/pair`. - [x] Check if is worth it to create `@coven/solid-pair` (they don't need this). -- [ ] Cleanup tests. -- [ ] Cleanup docs. +- [x] Cleanup tests (next is @coven/pair) +- [ ] Cleanup docs (all `@example` should have a description). - [ ] Start working on new `@simulcast/{name}` libs: - [ ] `@simulcast/angular`. - [ ] `@simulcast/preact`. diff --git a/deno.json b/deno.jsonc similarity index 89% rename from deno.json rename to deno.jsonc index 4272686..6266a06 100644 --- a/deno.json +++ b/deno.jsonc @@ -2,16 +2,18 @@ "$schema": "https://raw.githubusercontent.com/denoland/deno/refs/tags/v1.41.0/cli/schemas/config-file.v1.json", "compilerOptions": { "exactOptionalPropertyTypes": true, + "jsxFactory": "createElement", + "jsxFragmentFactory": "Fragment", "noFallthroughCasesInSwitch": true, "noImplicitOverride": true, "noImplicitReturns": true, "noUncheckedIndexedAccess": true, - "noUnusedLocals": true, + // "noUnusedLocals": true, // Handled by no-unused-vars "noUnusedParameters": true, - "strict": true, - "verbatimModuleSyntax": true + "strict": true + // "verbatimModuleSyntax": true // handled by verbatim-module-syntax }, - "exclude": [".git"], + "exclude": ["coverage"], "fmt": { "indentWidth": 4, "lineWidth": 80, @@ -24,7 +26,7 @@ "@std/assert": "jsr:@std/assert@^1.0.6", "@types/react": "npm:@types/react@^18.3.11", "@types/react-dom": "npm:@types/react-dom@^18.3.1", - "preact": "npm:preact@^10.24.2", + "preact": "npm:preact@^10.24.3", "preact-render-to-string": "npm:preact-render-to-string@^6.5.11", "react": "npm:react@^18.3.1", "react-dom": "npm:react-dom@^18.3.1" @@ -136,7 +138,9 @@ } }, "tasks": { - "test-docs": "deno test --doc --config ./deno.test--doc.jsonc" + "format-check": "deno fmt --check", + "lint-docs": "deno doc --lint ./**/*.ts", + "test-coverage": "deno test --coverage --doc --quiet" }, "workspace": [ "./@coven/compare", diff --git a/deno.test--doc.jsonc b/deno.test--doc.jsonc deleted file mode 100644 index 438ab9f..0000000 --- a/deno.test--doc.jsonc +++ /dev/null @@ -1,156 +0,0 @@ -// Sadly we have to keep this file in sync manually with `deno.json` until they -// support extension. This only exists so `deno test --doc` doesn't require -// locals to be used. -{ - "$schema": "https://raw.githubusercontent.com/denoland/deno/refs/tags/v1.41.0/cli/schemas/config-file.v1.json", - "compilerOptions": { - "exactOptionalPropertyTypes": true, - "noFallthroughCasesInSwitch": true, - "noImplicitOverride": true, - "noImplicitReturns": true, - "noUncheckedIndexedAccess": true, - "noUnusedLocals": false, // Set to false so `deno test --doc` works - "noUnusedParameters": true, - "strict": true, - "verbatimModuleSyntax": false // Set to false for convenience with `deno test --doc` - }, - "exclude": [".git"], - "fmt": { - "indentWidth": 4, - "lineWidth": 80, - "proseWrap": "always", - "semiColons": true, - "singleQuote": false, - "useTabs": true - }, - "imports": { - "@std/assert": "jsr:@std/assert@^1.0.6", - "@types/react": "npm:@types/react@^18.3.11", - "@types/react-dom": "npm:@types/react-dom@^18.3.1", - "preact": "npm:preact@^10.24.2", - "preact-render-to-string": "npm:preact-render-to-string@^6.5.11", - "react": "npm:react@^18.3.1", - "react-dom": "npm:react-dom@^18.3.1" - }, - "lint": { - "rules": { - "include": [ - "adjacent-overload-signatures", - "ban-ts-comment", - "ban-types", - "ban-unknown-rule-code", - "ban-untagged-ignore", - "ban-untagged-todo", - "ban-unused-ignore", - "camelcase", - "constructor-super", - "default-param-last", - "eqeqeq", - "explicit-function-return-type", - "explicit-module-boundary-types", - "for-direction", - "getter-return", - "guard-for-in", - "no-array-constructor", - "no-async-promise-executor", - "no-await-in-loop", - "no-await-in-sync-fn", - "no-boolean-literal-for-arguments", - "no-case-declarations", - "no-class-assign", - "no-compare-neg-zero", - "no-cond-assign", - "no-console", - "no-const-assign", - "no-constant-condition", - "no-control-regex", - "no-debugger", - "no-delete-var", - "no-deprecated-deno-api", - "no-dupe-args", - "no-dupe-class-members", - "no-dupe-else-if", - "no-dupe-keys", - "no-duplicate-case", - "no-empty", - "no-empty-character-class", - "no-empty-enum", - "no-empty-interface", - "no-empty-pattern", - "no-eval", - "no-ex-assign", - "no-explicit-any", - "no-external-import", - "no-extra-boolean-cast", - "no-extra-non-null-assertion", - "no-fallthrough", - "no-func-assign", - "no-global-assign", - "no-implicit-declare-namespace-export", - "no-import-assertions", - "no-import-assign", - "no-inferrable-types", - "no-inner-declarations", - "no-invalid-regexp", - "no-invalid-triple-slash-reference", - "no-irregular-whitespace", - "no-misused-new", - "no-namespace", - "no-new-symbol", - "no-node-globals", - "no-non-null-asserted-optional-chain", - "no-non-null-assertion", - "no-obj-calls", - "no-octal", - "no-process-globals", - "no-prototype-builtins", - "no-redeclare", - "no-regex-spaces", - "no-self-assign", - "no-self-compare", - "no-setter-return", - "no-shadow-restricted-names", - "no-sparse-arrays", - "no-sync-fn-in-async-fn", - "no-this-alias", - "no-this-before-super", - "no-throw-literal", - "no-top-level-await", - "no-unreachable", - "no-unsafe-finally", - "no-unsafe-negation", - "no-unused-labels", - "no-unused-vars", - "no-var", - "no-window", - "no-window-prefix", - "no-with", - "prefer-as-const", - "prefer-const", - "prefer-namespace-keyword", - "require-await", - "require-yield", - "single-var-declarator", - "triple-slash-reference", - "use-isnan", - "valid-typeof", - "verbatim-module-syntax" - ] - } - }, - "workspace": [ - "./@coven/compare", - "./@coven/constants", - "./@coven/cron", - "./@coven/expression", - "./@coven/iterables", - "./@coven/math", - "./@coven/pair", - "./@coven/parsers", - "./@coven/predicates", - "./@coven/terminal", - "./@coven/types", - "./@coven/utils", - "./@simulcast/core" - ] -} diff --git a/tests/@coven/cron/parseListMap.test.ts b/tests/@coven/cron/parseListMap.test.ts index 5959498..8f3a0e8 100644 --- a/tests/@coven/cron/parseListMap.test.ts +++ b/tests/@coven/cron/parseListMap.test.ts @@ -1,6 +1,6 @@ import { parseListMap } from "@coven/cron"; import { iterableToArray } from "@coven/iterables"; -import { assertEquals } from "@std/assert/equals"; +import { assertEquals } from "@std/assert"; Deno.test("List of valid and invalid values returns parsed list", () => assertEquals( diff --git a/tests/@coven/iterables/async/forEach.test.ts b/tests/@coven/iterables/async/forEach.test.ts index b38e5de..b036627 100644 --- a/tests/@coven/iterables/async/forEach.test.ts +++ b/tests/@coven/iterables/async/forEach.test.ts @@ -3,12 +3,12 @@ import { forEach } from "@coven/iterables/async"; import type { AwaitableIterable } from "@coven/types"; import { assertEquals } from "@std/assert"; -const forEachTest = (iterable: AwaitableIterable) => { +const forEachTest = async (iterable: AwaitableIterable) => { const output: Array = []; - return forEach((item: Item) => void output.push(item))(iterable).then( - (_) => output, - ); + await forEach((item: Item) => void output.push(item))(iterable); + + return output; }; Deno.test("a string loops over every letter of that string", async () => diff --git a/tests/@coven/iterables/async/iteratorFunctionToAsyncIterableIterator.test.ts b/tests/@coven/iterables/async/iteratorFunctionToAsyncIterableIterator.test.ts index 8e7214b..e3404f5 100644 --- a/tests/@coven/iterables/async/iteratorFunctionToAsyncIterableIterator.test.ts +++ b/tests/@coven/iterables/async/iteratorFunctionToAsyncIterableIterator.test.ts @@ -2,7 +2,7 @@ import { iterableToArray, iteratorFunctionToAsyncIterableIterator, } from "@coven/iterables/async"; -import { assertEquals } from "@std/assert/equals"; +import { assertEquals, assertRejects } from "@std/assert"; const numbers = [0, 1, 2, 3]; const iterableIteratorNumbers = iteratorFunctionToAsyncIterableIterator( @@ -26,6 +26,19 @@ const iterableIteratorSimple = iteratorFunctionToAsyncIterableIterator(() => { next: () => ({ done: done || ((done = true), false), value: 13 }), }; }); +const asyncIterableIteratorSimple = iteratorFunctionToAsyncIterableIterator( + () => { + let done = false; + + return ({ + next: () => + Promise.resolve({ + done: done || ((done = true), false), + value: 13, + }), + }); + }, +); Deno.test( "Iterable iterator that we'll run twice returns the values twice", @@ -39,6 +52,14 @@ Deno.test( ), ); +Deno.test( + "Iterable iterator throw exists and throws", + () => + void assertRejects( + async () => await iterableIteratorNumbers.throw?.("Test"), + ), +); + Deno.test( "Async Iterable iterator that we'll run twice returns the values twice", async () => @@ -62,3 +83,15 @@ Deno.test( [13, 13], ), ); + +Deno.test( + "AsyncIterator that only has next returns as many times as it's called", + async () => + assertEquals( + [ + ...(await iterableToArray(asyncIterableIteratorSimple)), + ...(await iterableToArray(asyncIterableIteratorSimple)), + ], + [13, 13], + ), +); diff --git a/tests/@coven/iterables/groupBy.test.ts b/tests/@coven/iterables/groupBy.test.ts index 1a84bef..9e48323 100644 --- a/tests/@coven/iterables/groupBy.test.ts +++ b/tests/@coven/iterables/groupBy.test.ts @@ -1,5 +1,5 @@ import { groupBy } from "@coven/iterables"; -import { assertEquals } from "@std/assert/equals"; +import { assertEquals } from "@std/assert"; const string1 = "string1"; const string2 = "string2"; diff --git a/tests/@coven/iterables/iteratorFunctionToIterableIterator.test.ts b/tests/@coven/iterables/iteratorFunctionToIterableIterator.test.ts index 4b9029e..39abb03 100644 --- a/tests/@coven/iterables/iteratorFunctionToIterableIterator.test.ts +++ b/tests/@coven/iterables/iteratorFunctionToIterableIterator.test.ts @@ -1,5 +1,5 @@ import { iteratorFunctionToIterableIterator } from "@coven/iterables"; -import { assertEquals } from "@std/assert/equals"; +import { assertEquals } from "@std/assert"; const numbers = [0, 1, 2, 3]; const iterableIteratorNumbers = iteratorFunctionToIterableIterator(() => diff --git a/tests/@coven/iterables/objectToentries.test.ts b/tests/@coven/iterables/objectToentries.test.ts index 3d74833..5855029 100644 --- a/tests/@coven/iterables/objectToentries.test.ts +++ b/tests/@coven/iterables/objectToentries.test.ts @@ -1,6 +1,6 @@ import { EMPTY_ARRAY, EMPTY_OBJECT } from "@coven/constants"; import { iterableToArray, objectToEntries } from "@coven/iterables"; -import { assertEquals } from "@std/assert/equals"; +import { assertEquals } from "@std/assert"; const symbol = Symbol("🟩"); diff --git a/tests/@coven/pair/preact.test.tsx b/tests/@coven/pair/preact.test.tsx index 6bf9631..b005f3f 100644 --- a/tests/@coven/pair/preact.test.tsx +++ b/tests/@coven/pair/preact.test.tsx @@ -21,13 +21,13 @@ const key = "TEST"; const PairedState = pair(useState); -Deno.test("Paired hook with key returns component wrapping hook and with key", () => +Deno.test("Generated HTML with a prop should be the same from using `pair` or doing everything manually", () => assertStrictEquals( renderToString({Render}), renderToString({Render}), )); -Deno.test("Paired hook without key returns component wrapping hook and without key", () => +Deno.test("Generated HTML should be the same from using `pair` or doing everything manually", () => assertStrictEquals( renderToString({Render}), renderToString({Render}), diff --git a/tests/@coven/pair/react.test.tsx b/tests/@coven/pair/react.test.tsx index 8cb8cd1..c5f1571 100644 --- a/tests/@coven/pair/react.test.tsx +++ b/tests/@coven/pair/react.test.tsx @@ -2,7 +2,9 @@ /** @jsxImportSourceTypes @types/react */ import { pair, type PairedComponentProperties } from "@coven/pair/react"; import { assertStrictEquals } from "@std/assert"; +// @deno-types="@types/react" import { useState } from "react"; +// @deno-types="@types/react-dom/server" import { renderToString } from "react-dom/server"; const Render = (usePairedState: typeof useState) => { @@ -22,13 +24,13 @@ const key = "TEST"; const PairedState = pair(useState); -Deno.test("Paired hook with key returns component wrapping hook and with key", () => +Deno.test("Generated HTML with a prop should be the same from using `pair` or doing everything manually", () => assertStrictEquals( renderToString({Render}), renderToString({Render}), )); -Deno.test("Paired hook without key returns component wrapping hook and without key", () => +Deno.test("Generated HTML should be the same from using `pair` or doing everything manually", () => assertStrictEquals( renderToString({Render}), renderToString({Render}), diff --git a/tests/@coven/parsers/attempt.test.ts b/tests/@coven/parsers/attempt.test.ts index cdce9b8..e5427be 100644 --- a/tests/@coven/parsers/attempt.test.ts +++ b/tests/@coven/parsers/attempt.test.ts @@ -15,9 +15,11 @@ const throwingFunction = (shouldThrow: boolean) => { const safeFunction = attempt(throwingFunction); Deno.test( - "When a function that could throw doesn't throw, it returns the expected value", + "Returns expected value when function doesn't throw", () => assertEquals(safeFunction(DOES_NOT_THROW), "success"), ); -Deno.test("When a function that could throw throws, it returns undefined", () => - assertEquals(safeFunction(THROWS), undefined)); +Deno.test( + "Returns undefined when function throw", + () => assertEquals(safeFunction(THROWS), undefined), +); diff --git a/tests/@coven/predicates/hasPrototype.test.ts b/tests/@coven/predicates/hasPrototype.test.ts new file mode 100644 index 0000000..3c3f6ee --- /dev/null +++ b/tests/@coven/predicates/hasPrototype.test.ts @@ -0,0 +1,13 @@ +import { hasPrototype } from "@coven/predicates"; +import { assert, assertFalse } from "@std/assert"; + +Deno.test("Array instance doesn't have prototype", () => + assertFalse(hasPrototype([]))); + +Deno.test("Array constructor has prototype", () => assert(hasPrototype(Array))); + +Deno.test("Object instance doesn't have prototype", () => + assertFalse(hasPrototype({}))); + +Deno.test("Object constructor has prototype", () => + assert(hasPrototype(Object))); diff --git a/tests/@coven/predicates/isSafeInteger.test.ts b/tests/@coven/predicates/isSafeInteger.test.ts deleted file mode 100644 index 9490c78..0000000 --- a/tests/@coven/predicates/isSafeInteger.test.ts +++ /dev/null @@ -1,10 +0,0 @@ -import { isSafeInteger } from "@coven/predicates"; -import { assert, assertFalse } from "@std/assert"; - -Deno.test("a safe integer", () => assert(isSafeInteger(1))); - -Deno.test("a float", () => assertFalse(isSafeInteger(1.5))); - -Deno.test("a negative integer", () => assert(isSafeInteger(-1))); - -Deno.test("a negative float", () => assertFalse(isSafeInteger(-1.5))); diff --git a/tests/@simulcast/core/broadcast.test.ts b/tests/@simulcast/core/broadcast.test.ts index a97030e..1b5cb3e 100644 --- a/tests/@simulcast/core/broadcast.test.ts +++ b/tests/@simulcast/core/broadcast.test.ts @@ -1,6 +1,5 @@ import { broadcast } from "@simulcast/core"; -import { assert } from "@std/assert"; -import { assertStrictEquals } from "@std/assert/strict-equals"; +import { assert, assertStrictEquals } from "@std/assert"; const TEST_EVENT = "test";