@murky-web/typebuddy 0.1.0

package/dist/type_helper.js

@@ -0,0 +1,296 @@
+//#region src/type_helper.ts
+const EMPTY_LENGTH = 0;
+const uuidRegex = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$/;
+const ulidRegex = /^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$/;
+function cloneDefaultArray(defaultValue) {
+	if (!defaultValue) return defaultValue;
+	return [...defaultValue];
+}
+/**
+* Checks if the provided result is a `Success` type.
+*
+* @template T The type of the value contained in the `Success` type.
+* @param {Readonly<Success<T> | Failed>} result The result to check, which can
+* be either a `Success<T>` or `Failed`.
+* @returns {boolean} `true` if the result is a `Success<T>`, `false` if it is a `Failed`.
+* This function acts as a type guard, narrowing the type of `result`
+* to `Success<T>` when the condition is met.
+* @example
+* ```typescript
+* const result = await someAsyncFunction();
+* if (isSuccess(result)) {
+*   return result.value; // TypeScript knows `value` is of type `T`
+* }
+* ```
+*/
+function isSuccess(result) {
+	return !result.isError;
+}
+function isString(value) {
+	return typeof value === "string";
+}
+/**
+* Parses the input value as a boolean. Returns false if the value is no string.
+* @param {unknown} value - The value to check.
+* @returns {boolean} True if the value is a string.
+*/
+function isEmptyString(value) {
+	if (!isString(value)) return false;
+	return value.trim() === "";
+}
+/**
+* Returns true if the value is null.
+* @param {unknown} value - The value to check.
+* @returns {boolean} True if the value is null.
+*/
+function isNull(value) {
+	return value === null;
+}
+/**
+* Returns true if the value is undefined.
+* @param {unknown} value - The value to check.
+* @returns {boolean} True if the value is undefined.
+*/
+function isUndefined(value) {
+	return typeof value === "undefined";
+}
+/**
+* Checks whether an Optional value is currently in its missing state.
+* @param {Optional<T>} value - The Optional value to check.
+* @returns {boolean} True when the value is undefined.
+*/
+function isOptional(value) {
+	return isUndefined(value);
+}
+/**
+* Checks whether a Maybe value is currently in its missing state.
+* @param {Maybe<T>} value - The Maybe value to check.
+* @returns {boolean} True when the value is null.
+*/
+function isMaybe(value) {
+	return isNull(value);
+}
+/**
+* Checks whether a Nullable value is currently in its missing state.
+* @param {Nullable<T>} value - The Nullable value to check.
+* @returns {boolean} True when the value is null or undefined.
+*/
+function isNullable(value) {
+	return isNull(value) || isUndefined(value);
+}
+function isArray(value) {
+	return Array.isArray(value);
+}
+function isEmptyArray(value) {
+	return Array.isArray(value) && value.length === EMPTY_LENGTH;
+}
+function fastIsArray(value) {
+	return Object.prototype.toString.call(value) === "[object Array]";
+}
+function isNumber(value) {
+	if (typeof value === "string" && value.trim() === "") return false;
+	return typeof value === "number" && !Number.isNaN(value) && Number.isFinite(value);
+}
+function isObject(value) {
+	if (typeof value !== "object" || value === null || isArray(value) || Object.prototype.toString.call(value) !== "[object Object]") return false;
+	const objectValue = value;
+	return Object.getPrototypeOf(objectValue) === Object.prototype;
+}
+function isBoolean(value) {
+	return typeof value === "boolean";
+}
+function isFunction(value) {
+	return typeof value === "function";
+}
+function isPromise(value) {
+	if (typeof value !== "object" || value === null) return false;
+	return typeof Reflect.get(value, "then") === "function";
+}
+function isError(value) {
+	return value instanceof Error;
+}
+function isDate(value) {
+	return value instanceof Date;
+}
+function isRegExp(value) {
+	return value instanceof RegExp;
+}
+function isSymbol(value) {
+	return typeof value === "symbol";
+}
+function isEmptyObject(value) {
+	return typeof value === "object" && !isNull(value) && !isUndefined(value) && !isEmptyArray(value) && Object.getPrototypeOf(value) === Object.prototype && Object.keys(value).length === EMPTY_LENGTH;
+}
+/**
+* Check if a value is an instance of a class.
+* @param {unknown} value - The value to check.
+* @param {unknown} constructor - The class constructor to check against.
+* @returns {boolean} True if the value is an instance of the class.
+*/
+function isInstanceOf(value, constructor) {
+	return value instanceof constructor;
+}
+/**
+* Get the keys of an object.
+* @param {unknown} object - The object to get the keys of.
+* @returns {Array} Keys of object.
+*/
+function getKeys(object) {
+	return Object.keys(object);
+}
+function parseInteger(value, defaultValue) {
+	if (isNumber(value)) return Math.floor(value);
+	if (isString(value)) {
+		const parsed = Number(value.trim());
+		if (Number.isInteger(parsed)) return parsed;
+	}
+	return defaultValue;
+}
+/**
+* Check if a value is an integer.
+* @param {unknown} value - The value to check.
+* @returns {boolean} True if the value is an integer.
+*/
+function isInteger(value) {
+	return typeof value === "number" && Number.isInteger(value);
+}
+/**
+* Check if a value is a float.
+* @param {unknown} value - The value to check.
+* @returns {boolean} True if the value is a float.
+*/
+function isFloat(value) {
+	return typeof value === "number" && !Number.isNaN(value) && !Number.isInteger(value);
+}
+function parseFloat(value, defaultValue) {
+	if (isNumber(value)) return value;
+	if (isString(value)) {
+		const normalizedValue = value.trim().replace(",", ".");
+		const parsed = Number.parseFloat(normalizedValue);
+		if (!Number.isNaN(parsed)) return parsed;
+	}
+	return defaultValue;
+}
+function parseNumber(value, defaultValue) {
+	if (isNumber(value)) return value;
+	if (isString(value)) {
+		const normalizedValue = value.trim().replace(",", ".");
+		const parsed = Number(normalizedValue);
+		if (Number.isFinite(parsed)) return parsed;
+	}
+	return defaultValue;
+}
+/**
+* Parses the input value as a string. Returns an empty string if the
+* value cannot be converted.
+* @param {unknown} value - The value to check.
+* @param {Optional<string>} defaultValue - Value gets returned if string could not
+* be parsed.
+* @returns {string} The parsed string.
+*/
+function parseString(value, defaultValue = "") {
+	if (isString(value)) return value;
+	if (isNumber(value)) return value.toString();
+	if (typeof value === "boolean") return value.toString();
+	return defaultValue;
+}
+/**
+* Returns true for values that behave like "empty" application input.
+* @param {unknown} value - The value to check.
+* @returns {boolean} True if the value is nullish, empty string, empty array,
+* false, or a plain object whose values are all empty-like.
+*/
+function isEmptyLike(value) {
+	if (isNull(value) || isUndefined(value)) return true;
+	if (isString(value)) return isEmptyString(value);
+	if (isArray(value)) return value.every((entry) => {
+		return isEmptyLike(entry);
+	});
+	if (isBoolean(value)) return !value;
+	if (isObject(value)) {
+		if (Object.getPrototypeOf(value) !== Object.prototype) return false;
+		return Object.values(value).every((entry) => {
+			return isEmptyLike(entry);
+		});
+	}
+	return false;
+}
+/**
+* Checks if the provided value contains empty values.
+*
+* This function determines if the given value is either an empty string,
+* an empty object, or a string representation of an empty object.
+*
+* @param {unknown} value - The value to check for emptiness. It can be of any type.
+* @returns {boolean} `true` if the value is an empty string, an empty object, or a string
+*          representation of an empty object; otherwise, `false`.
+*/
+function hasEmptyValues(value) {
+	if (isString(value)) {
+		try {
+			if (isEmptyObject(JSON.parse(value))) return true;
+		} catch {
+			return isEmptyString(value);
+		}
+		return isEmptyString(value);
+	}
+	return isEmptyObject(value);
+}
+function parseArray(value, defaultValue) {
+	if (isArray(value)) return [...value];
+	if (isString(value)) return value.split(/[,|;\n\t ]+/).map((entry) => {
+		return entry.trim();
+	}).filter((entry) => {
+		return entry.length > EMPTY_LENGTH;
+	});
+	if (isNumber(value)) return [value];
+	if (isEmptyObject(value)) return [value];
+	if (isNull(value) || isUndefined(value)) return cloneDefaultArray(defaultValue);
+	return cloneDefaultArray(defaultValue);
+}
+/**
+* Compares two arrays and returns true if they have at least one common value.
+* @param {readonly T[]} array1 - First array.
+* @param {readonly T[]} array2 - Second array.
+* @returns {boolean} True if the arrays have at least one common value.
+*/
+function arrayContainsCommonValue(array1, array2) {
+	if (!isArray(array1) || !isArray(array2)) return false;
+	const valueOccurrences = new Set(array1);
+	return array2.some((value) => {
+		return valueOccurrences.has(value);
+	});
+}
+/**
+* Returns true if the input is a UUID string.
+* @param {string} input - The input to check.
+* @returns {boolean} True if the input is a UUID string.
+*/
+function isUuidString(input) {
+	return isString(input) && uuidRegex.test(input);
+}
+/**
+* Returns true if the input is a ULID string.
+* @param {string }input - The input to check.
+* @returns {boolean} True if the input is a ULID string.
+*/
+function isUlidString(input) {
+	return typeof input === "string" && ulidRegex.test(input);
+}
+function parseDomainName(url, defaultValue) {
+	const normalizedValue = url.trim();
+	if (normalizedValue === "" || normalizedValue.startsWith("/")) return defaultValue;
+	let urlCandidate = normalizedValue;
+	if (!normalizedValue.includes("://")) urlCandidate = `https://${normalizedValue}`;
+	let hostname = "";
+	try {
+		({hostname} = new URL(urlCandidate));
+	} catch {
+		return defaultValue;
+	}
+	const [domainName] = hostname.replace(/^www\d?\./i, "").split(".");
+	if (!domainName) return defaultValue;
+	return domainName;
+}
+//#endregion
+export { arrayContainsCommonValue, fastIsArray, getKeys, hasEmptyValues, isArray, isBoolean, isDate, isEmptyArray, isEmptyLike, isEmptyObject, isEmptyString, isError, isFloat, isFunction, isInstanceOf, isInteger, isMaybe, isNull, isNullable, isNumber, isObject, isOptional, isPromise, isRegExp, isString, isSuccess, isSymbol, isUlidString, isUndefined, isUuidString, parseArray, parseDomainName, parseFloat, parseInteger, parseNumber, parseString };

package/globals.ts

@@ -0,0 +1,60 @@
+import type {
+  JsonifiedObject as JsonifiedObjectImport,
+  JsonifiedValue as JsonifiedValueImport,
+  Stringified as StringifiedImport,
+} from "./src/types/json.js";
+import type { Maybe as MaybeImport, ResolveMaybe as ResolveMaybeImport } from "./src/types/maybe.js";
+import type {
+  Failed as FailedImport,
+  MaybePromise as MaybePromiseImport,
+  Success as SuccessImport,
+} from "./src/types/maybe_promise.js";
+import type {
+  Nullable as NullableImport,
+  ResolveNullable as ResolveNullableImport,
+} from "./src/types/nullable.js";
+import type {
+  Optional as OptionalImport,
+  ResolveOptional as ResolveOptionalImport,
+} from "./src/types/optional.js";
+
+declare global {
+  type Failed<T extends null = null> = FailedImport<T>;
+  type JsonifiedValue<T> = JsonifiedValueImport<T>;
+  type Maybe<T> = MaybeImport<T>;
+  type MaybePromise<T> = MaybePromiseImport<T>;
+  type Nullable<T> = NullableImport<T>;
+  type Optional<T> = OptionalImport<T>;
+  type ResolveMaybe<T, R extends Maybe<T>> = ResolveMaybeImport<T, R>;
+  type ResolveNullable<T, R extends Nullable<T>> = ResolveNullableImport<T, R>;
+  type ResolveOptional<T, R extends Optional<T>> = ResolveOptionalImport<T, R>;
+  type Stringified<T> = StringifiedImport<T>;
+  type Success<T> = SuccessImport<T>;
+
+  interface JSON {
+    stringify<T>(
+      value: T,
+      replacer?: null,
+      space?: string | number,
+    ): Stringified<T>;
+
+    parse<T>(
+      str: Stringified<T>,
+      replacer?: null,
+    ): JsonifiedObjectImport<T>;
+  }
+}
+
+export type {
+  FailedImport as Failed,
+  JsonifiedValueImport as JsonifiedValue,
+  MaybeImport as Maybe,
+  MaybePromiseImport as MaybePromise,
+  NullableImport as Nullable,
+  OptionalImport as Optional,
+  ResolveMaybeImport as ResolveMaybe,
+  ResolveNullableImport as ResolveNullable,
+  ResolveOptionalImport as ResolveOptional,
+  StringifiedImport as Stringified,
+  SuccessImport as Success,
+};

package/jsr.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://jsr.io/schema/config-file.v1.json",
+  "name": "@murky-web/typebuddy",
+  "version": "0.1.0",
+  "license": "ISC",
+  "exports": {
+    ".": "./src/index.ts",
+    "./biome": "./biome/index.ts",
+    "./oxlint": "./oxlint/index.ts"
+  },
+  "publish": {
+    "include": [
+      "README.md",
+      "src/**/*.ts",
+      "oxlint/**/*.ts",
+      "rules/**/*.ts",
+      "biome/**/*.ts",
+      "biome/*.grit",
+      "biome/*.gritt"
+    ],
+    "exclude": [
+      "tests/**",
+      "smoke/**",
+      "globals.ts",
+      "dist/**",
+      "node_modules/**"
+    ]
+  }
+}

package/oxlint/index.ts

@@ -0,0 +1,30 @@
+import { requireTryCatchAsyncRule } from "../rules/async_rule.js";
+import { errorSafeAsyncRule } from "../rules/maybe_promise_rule.js";
+import { maybeRule } from "../rules/maybe_rule.js";
+import { nullableRule } from "../rules/nullable_rule.js";
+import { optionalRule } from "../rules/optional_rule.js";
+
+const rules = {
+  "prefer-maybe": maybeRule,
+  "prefer-maybe-promise": errorSafeAsyncRule,
+  "prefer-nullable": nullableRule,
+  "prefer-optional": optionalRule,
+  "require-try-catch": requireTryCatchAsyncRule,
+} as const satisfies Record<string, unknown>;
+
+type TypebuddyOxlintPlugin = {
+  meta: {
+    name: string;
+  };
+  rules: Record<string, unknown>;
+};
+
+const plugin: TypebuddyOxlintPlugin = {
+  meta: {
+    name: "typebuddy",
+  },
+  rules,
+};
+
+export default plugin;
+export { plugin as typebuddyOxlintPlugin };

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@murky-web/typebuddy",
+  "version": "0.1.0",
+  "description": "Your new best friend for simple typescript guards every project needs.",
+  "private": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./globals": {
+      "types": "./globals.ts",
+      "import": "./dist/globals.js",
+      "default": "./dist/globals.js"
+    },
+    "./oxlint": {
+      "types": "./oxlint/index.ts",
+      "import": "./dist/oxlint.js",
+      "default": "./dist/oxlint.js"
+    },
+    "./biome": {
+      "types": "./biome/index.ts",
+      "import": "./dist/biome.js",
+      "default": "./dist/biome.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "build:local": "bun run build",
+    "build": "bun run clean && tsdown && cp ./biome/*.grit ./dist/ && cp ./biome/*.gritt ./dist/",
+    "clean": "rm -rf dist",
+    "lint": "oxlint -c ./.oxlintrc.jsonc --tsconfig ./tsconfig.lint.json --type-aware src biome tsdown.config.ts vitest.config.ts",
+    "lint:fix": "oxlint -c ./.oxlintrc.jsonc --tsconfig ./tsconfig.lint.json --type-aware --fix src biome tsdown.config.ts vitest.config.ts",
+    "format": "oxfmt -c ../../node_modules/@murky-web/config/oxc/.oxfmtrc.jsonc src rules biome tests tsdown.config.ts vitest.config.ts",
+    "format:check": "oxfmt -c ../../node_modules/@murky-web/config/oxc/.oxfmtrc.jsonc --check src rules biome tests tsdown.config.ts vitest.config.ts",
+    "smoke:globals": "bun run build && tsgo --project ./smoke/globals/tsconfig.json --noEmit",
+    "smoke:oxlint": "bun run build && bun ./smoke/oxlint/run-smoke.ts",
+    "smoke:oxlint:fix": "bun run build && bun ./smoke/oxlint/run-fix-smoke.ts",
+    "smoke:treeshake": "bun run build && bun ./smoke/treeshake/run.ts",
+    "typecheck": "tsgo --project ./tsconfig.json --noEmit && tsgo --project ./tsconfig.vitest.json --noEmit"
+  },
+  "files": [
+    "dist",
+    "globals.ts",
+    "jsr.json",
+    "src/index.ts",
+    "src/type_helper.ts",
+    "src/types",
+    "oxlint/index.ts",
+    "biome",
+    "rules"
+  ],
+  "license": "ISC",
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "provenance":false 
+  },
+  "devDependencies": {
+    "@murky-web/config": "workspace:*"
+  }
+}

package/rules/async_rule.ts

@@ -0,0 +1,98 @@
+type AstNode = {
+  type: string;
+  body?: AstNode | AstNode[];
+  async?: boolean;
+  range?: [number, number];
+  [key: string]: unknown;
+};
+
+type RuleContext = {
+  getSourceCode(): { getText(node: unknown): string };
+  report(descriptor: {
+    node: unknown;
+    messageId: string;
+    fix(
+      fixer: {
+        replaceText(node: unknown, text: string): unknown;
+      },
+    ): unknown;
+  }): void;
+};
+
+function hasTryCatch(nodes: AstNode[]): boolean {
+  return nodes.some((node) => {return node.type === "TryStatement"});
+}
+
+const rule = {
+  create(context: RuleContext) {
+    const sourceCode = context.getSourceCode();
+
+    function getIndentation(node: AstNode): string {
+      const lines = sourceCode.getText(node).split("\n");
+      const firstLine = lines[0];
+      const match = /^\s*/.exec(firstLine);
+      return match ? match[0] : "";
+    }
+
+    function wrapInTryCatch(node: AstNode): string {
+      const body = Array.isArray(node.body) ? node.body : [];
+      const indent = getIndentation(node);
+      const innerIndent = `${indent}  `;
+      const bodyText = body
+        .map((statement) => {
+          const text = sourceCode.getText(statement);
+          return `${innerIndent}${text.replaceAll(/^\s*/gm, "")}`;
+        })
+        .join("\n");
+
+      return `{
+${indent}try {
+${bodyText}
+${indent}} catch (err) {
+${innerIndent}return FAILED_PROMISE;
+${indent}}
+}`;
+    }
+
+    function checkFunction(node: AstNode) {
+      if (node.async !== true) return;
+      const bodyNode = node.body;
+      if (!bodyNode || Array.isArray(bodyNode) || bodyNode.type !== "BlockStatement") {
+        return;
+      }
+
+      const body = Array.isArray(bodyNode.body) ? bodyNode.body : [];
+      if (hasTryCatch(body)) return;
+
+      context.report({
+        node,
+        messageId: "missingTryCatch",
+        fix(fixer) {
+          return fixer.replaceText(bodyNode, wrapInTryCatch(bodyNode));
+        },
+      });
+    }
+
+    return {
+      FunctionDeclaration: checkFunction,
+      FunctionExpression: checkFunction,
+      ArrowFunctionExpression: checkFunction,
+    };
+  },
+  defaultOptions: [],
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Async functions should have a try-catch block returning FAILED_PROMISE.",
+    },
+    fixable: "code",
+    schema: [],
+    messages: {
+      missingTryCatch:
+        "Async functions must have a try-catch block returning FAILED_PROMISE.",
+    },
+  },
+};
+
+export { rule as requireTryCatchAsyncRule };