@murky-web/typebuddy 1.0.0 → 1.1.0

package/README.md

@@ -150,12 +150,34 @@ That makes these names available globally:
 
 ### Utility Functions
 
+-   `ok(value)` and `err()` helpers for `MaybePromise` result objects
 -   `getKeys<T extends Record<string, unknown>>(object: T): Array<keyof T>`
 -   `arrayContainsCommonValue<T>(array1: T[], array2: T[]): boolean`
 -   `isEmptyString(value: unknown): boolean`
 -   `isEmptyLike(value: unknown): boolean`
 -   `hasEmptyValues(value: unknown): boolean`
 
+### Result Helpers
+
+Use these when you want small Rust-like `Ok` and `Err` ergonomics without
+hand-writing result objects:
+
+```typescript
+import { err, ok } from "@murky-web/typebuddy";
+
+export async function loadName(): MaybePromise<string> {
+    try {
+        return ok("murky");
+    } catch {
+        return err();
+    }
+}
+
+export async function flush(): MaybePromise<void> {
+    return ok();
+}
+```
+
 ### Types
 
 -   `Optional<T>`

package/dist/index.js

@@ -1,2 +1,2 @@
-import { 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 } from "./src/type_helper.js";
-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 };
+import { arrayContainsCommonValue, err, 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, ok, parseArray, parseDomainName, parseFloat, parseInteger, parseNumber, parseString } from "./src/type_helper.js";
+export { arrayContainsCommonValue, err, 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, ok, parseArray, parseDomainName, parseFloat, parseInteger, parseNumber, parseString };

package/dist/rules/async_rule.js

@@ -4,6 +4,12 @@ function hasTryCatch(nodes) {
 		return node.type === "TryStatement";
 	});
 }
+function isCallArgumentCallback(node) {
+	const parent = node.parent;
+	if (!parent) return false;
+	if (parent.type !== "CallExpression" && parent.type !== "NewExpression") return false;
+	return Array.isArray(parent.arguments) && parent.arguments.includes(node);
+}
 const rule = {
 	create(context) {
 		const sourceCode = context.getSourceCode();
@@ -22,12 +28,13 @@ ${body.map((statement) => {
 				return `${innerIndent}${sourceCode.getText(statement).replaceAll(/^\s*/gm, "")}`;
 			}).join("\n")}
 ${indent}} catch (err) {
-${innerIndent}return FAILED_PROMISE;
+${innerIndent}return { isError: true, value: null };
 ${indent}}
 }`;
 		}
 		function checkFunction(node) {
 			if (node.async !== true) return;
+			if (isCallArgumentCallback(node)) return;
 			const bodyNode = node.body;
 			if (!bodyNode || Array.isArray(bodyNode) || bodyNode.type !== "BlockStatement") return;
 			if (hasTryCatch(Array.isArray(bodyNode.body) ? bodyNode.body : [])) return;
@@ -48,10 +55,10 @@ ${indent}}
 	defaultOptions: [],
 	meta: {
 		type: "suggestion",
-		docs: { description: "Async functions should have a try-catch block returning FAILED_PROMISE." },
+		docs: { description: "Async functions should have a try-catch block returning an error result." },
 		fixable: "code",
 		schema: [],
-		messages: { missingTryCatch: "Async functions must have a try-catch block returning FAILED_PROMISE." }
+		messages: { missingTryCatch: "Async functions must have a try-catch block returning an error result." }
 	}
 };
 //#endregion

package/dist/rules/maybe_promise_rule.js

@@ -8,6 +8,24 @@ function isAsyncFunction(node) {
 function hasTypeParameters(value) {
 	return isNode(value) && Array.isArray(value.params);
 }
+function isCallArgumentCallback(node) {
+	const parent = node.parent;
+	if (!parent) return false;
+	if (parent.type !== "CallExpression" && parent.type !== "NewExpression") return false;
+	return Array.isArray(parent.arguments) && parent.arguments.includes(node);
+}
+function isIdentifierNamed(node, name) {
+	return isNode(node) && node.type === "Identifier" && node.name === name;
+}
+function isResultHelperCall(node, name) {
+	return isNode(node) && node.type === "CallExpression" && isIdentifierNamed(node.callee, name);
+}
+function hasIsErrorFlag(node, expected) {
+	if (!isNode(node) || node.type !== "ObjectExpression" || !Array.isArray(node.properties)) return false;
+	return node.properties.some((property) => {
+		return isNode(property) && property.type === "Property" && isIdentifierNamed(property.key, "isError") && isNode(property.value) && property.value.type === "Literal" && property.value.value === expected;
+	});
+}
 const rule = {
 	create(context) {
 		const sourceCode = context.getSourceCode();
@@ -32,6 +50,7 @@ const rule = {
 		}
 		function checkReturnType(node) {
 			if (!isAsyncFunction(node)) return;
+			if (isCallArgumentCallback(node)) return;
 			if (!isNode(node.returnType)) return;
 			const typeAnnotation = node.returnType.typeAnnotation;
 			if (!isTypeReference(typeAnnotation)) return;
@@ -53,13 +72,14 @@ const rule = {
 					node,
 					messageId: "returnVoidPromise",
 					fix(fixer) {
-						return fixer.replaceText(node, "return VOID_PROMISE");
+						return fixer.replaceText(node, "return { isError: false, value: undefined }");
 					}
 				});
 				return;
 			}
 			if (argument.type === "Identifier" && (argument.name === "VOID_PROMISE" || argument.name === "FAILED_PROMISE")) return;
-			if (!(argument.type === "ObjectExpression" && Array.isArray(argument.properties) && argument.properties.some((property) => isNode(property) && property.type === "Property" && isNode(property.key) && property.key.type === "Identifier" && property.key.name === "isError"))) context.report({
+			if (isResultHelperCall(argument, "ok") || isResultHelperCall(argument, "err")) return;
+			if (!hasIsErrorFlag(argument, true) && !hasIsErrorFlag(argument, false)) context.report({
 				node: argument,
 				messageId: "wrapReturn",
 				fix(fixer) {
@@ -81,6 +101,7 @@ const rule = {
 				parent = parent.parent;
 			}
 			if (!isAsync || !parentFunction) return;
+			if (isCallArgumentCallback(parentFunction)) return;
 			let returnType = null;
 			if (isNode(parentFunction.returnType)) {
 				const typeAnnotation = parentFunction.returnType.typeAnnotation;
@@ -90,17 +111,17 @@ const rule = {
 			for (const statement of blockBody) if (isNode(statement) && statement.type === "ReturnStatement") wrapReturnValue(statement, isAsync, returnType);
 			if (!isNode(node.handler) || !isNode(node.handler.body)) return;
 			const catchBody = Array.isArray(node.handler.body.body) ? node.handler.body.body.filter(isNode) : [];
-			if (!catchBody.some((statement) => statement.type === "ReturnStatement" && isNode(statement.argument) && statement.argument.type === "Identifier" && statement.argument.name === "FAILED_PROMISE")) context.report({
+			if (!catchBody.some((statement) => statement.type === "ReturnStatement" && isNode(statement.argument) && (statement.argument.type === "Identifier" && statement.argument.name === "FAILED_PROMISE" || isResultHelperCall(statement.argument, "err") || hasIsErrorFlag(statement.argument, true)))) context.report({
 				node: node.handler,
 				messageId: "returnFailedPromise",
 				fix(fixer) {
 					const lastStatement = catchBody.at(-1);
-					if (lastStatement?.type === "ReturnStatement" && isNode(lastStatement.argument) && lastStatement.argument.type === "ObjectExpression") return fixer.replaceText(lastStatement, "return FAILED_PROMISE");
+					if (lastStatement?.type === "ReturnStatement" && isNode(lastStatement.argument) && lastStatement.argument.type === "ObjectExpression") return fixer.replaceText(lastStatement, "return { isError: true, value: null }");
 					const handler = node.handler;
 					if (!isNode(handler)) return null;
 					const bodyRange = handler.body;
 					if (!isNode(bodyRange) || !Array.isArray(bodyRange.range)) return null;
-					return fixer.insertTextBeforeRange([bodyRange.range[1] - 1, bodyRange.range[1] - 1], "return FAILED_PROMISE; ");
+					return fixer.insertTextBeforeRange([bodyRange.range[1] - 1, bodyRange.range[1] - 1], "return { isError: true, value: null }; ");
 				}
 			});
 		}
@@ -123,8 +144,8 @@ const rule = {
 		messages: {
 			replaceWithMaybePromise: "Use 'MaybePromise' instead of 'Promise' as the return type in async functions.",
 			wrapReturn: "Wrap return value with { value: value, isError: false }.",
-			returnVoidPromise: "Return VOID_PROMISE for async functions with Promise<void> return type.",
-			returnFailedPromise: "Return FAILED_PROMISE in catch block of async functions."
+			returnVoidPromise: "Return a success result object for async functions with Promise<void> return type.",
+			returnFailedPromise: "Return an error result object in the catch block of async functions."
 		}
 	}
 };

package/dist/src/type_helper.js

@@ -26,6 +26,20 @@ function cloneDefaultArray(defaultValue) {
 function isSuccess(result) {
 	return !result.isError;
 }
+function ok(...args) {
+	const [value] = args;
+	return {
+		isError: false,
+		value
+	};
+}
+function err(...args) {
+	const [value] = args;
+	return {
+		isError: true,
+		value: value ?? null
+	};
+}
 function isString(value) {
 	return typeof value === "string";
 }
@@ -292,4 +306,4 @@ function parseDomainName(url, 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 };
+export { arrayContainsCommonValue, err, 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, ok, parseArray, parseDomainName, parseFloat, parseInteger, parseNumber, parseString };

package/jsr.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://jsr.io/schema/config-file.v1.json",
   "name": "@murky-web/typebuddy",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "license": "ISC",
   "exports": {
     ".": "./src/index.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@murky-web/typebuddy",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Your new best friend for simple typescript guards every project needs.",
   "private": false,
   "main": "./dist/index.js",

package/rules/async_rule.ts

@@ -1,98 +1,120 @@
 type AstNode = {
-  type: string;
-  body?: AstNode | AstNode[];
-  async?: boolean;
-  range?: [number, number];
-  [key: string]: unknown;
+    type: string;
+    body?: AstNode | AstNode[];
+    async?: boolean;
+    parent?: AstNode;
+    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;
+    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"});
+    return nodes.some((node) => {
+        return node.type === "TryStatement";
+    });
 }
 
-const rule = {
-  create(context: RuleContext) {
-    const sourceCode = context.getSourceCode();
+function isCallArgumentCallback(node: AstNode): boolean {
+    const parent = node.parent;
+    if (!parent) {
+        return false;
+    }
 
-    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] : "";
+    if (parent.type !== "CallExpression" && parent.type !== "NewExpression") {
+        return false;
     }
 
-    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 Array.isArray(parent.arguments) && parent.arguments.includes(node);
+}
+
+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] : "";
+        }
 
-      return `{
+        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;
+${innerIndent}return { isError: true, value: null };
 ${indent}}
 }`;
-    }
+        }
 
-    function checkFunction(node: AstNode) {
-      if (node.async !== true) return;
-      const bodyNode = node.body;
-      if (!bodyNode || Array.isArray(bodyNode) || bodyNode.type !== "BlockStatement") {
-        return;
-      }
+        function checkFunction(node: AstNode) {
+            if (node.async !== true) return;
+            if (isCallArgumentCallback(node)) 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;
+            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));
-        },
-      });
-    }
+            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.",
+        return {
+            FunctionDeclaration: checkFunction,
+            FunctionExpression: checkFunction,
+            ArrowFunctionExpression: checkFunction,
+        };
     },
-    fixable: "code",
-    schema: [],
-    messages: {
-      missingTryCatch:
-        "Async functions must have a try-catch block returning FAILED_PROMISE.",
+    defaultOptions: [],
+    meta: {
+        type: "suggestion",
+        docs: {
+            description:
+                "Async functions should have a try-catch block returning an error result.",
+        },
+        fixable: "code",
+        schema: [],
+        messages: {
+            missingTryCatch:
+                "Async functions must have a try-catch block returning an error result.",
+        },
     },
-  },
 };
 
 export { rule as requireTryCatchAsyncRule };