@reasonabletech/utils 0.1.0

package/dist/string.js

@@ -0,0 +1,48 @@
+// src/string.ts
+function isEmptyString(value) {
+  return value == null || value.trim().length === 0;
+}
+function isNonEmptyString(value) {
+  return value != null && value.trim().length > 0;
+}
+function truncateString(str, maxLength) {
+  if (str.length <= maxLength) {
+    return str;
+  }
+  return `${str.slice(0, maxLength - 3)}...`;
+}
+function capitalize(str) {
+  if (str.length === 0) {
+    return str;
+  }
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+function encodeBase64Url(data) {
+  const base64 = Buffer.from(data).toString("base64");
+  return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+function decodeBase64Url(encoded) {
+  const base64 = encoded.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = base64 + "=".repeat((4 - base64.length % 4) % 4);
+  return Buffer.from(padded, "base64");
+}
+function isValidBase64Url(str) {
+  const base64UrlRegex = /^[A-Za-z0-9_-]*$/;
+  return base64UrlRegex.test(str);
+}
+function getErrorMessage(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (typeof error === "string") {
+    return error;
+  }
+  if (typeof error === "object" && error !== null && "message" in error && typeof error.message === "string") {
+    return error.message;
+  }
+  return String(error);
+}
+
+export { capitalize, decodeBase64Url, encodeBase64Url, getErrorMessage, isEmptyString, isNonEmptyString, isValidBase64Url, truncateString };
+//# sourceMappingURL=string.js.map
+//# sourceMappingURL=string.js.map

package/dist/string.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/string.ts"],"names":[],"mappings":";AASO,SAAS,cAAc,KAAA,EAA2C;AACvE,EAAA,OAAO,KAAA,IAAS,IAAA,IAAQ,KAAA,CAAM,IAAA,GAAO,MAAA,KAAW,CAAA;AAClD;AAOO,SAAS,iBACd,KAAA,EACiB;AACjB,EAAA,OAAO,KAAA,IAAS,IAAA,IAAQ,KAAA,CAAM,IAAA,GAAO,MAAA,GAAS,CAAA;AAChD;AAQO,SAAS,cAAA,CAAe,KAAa,SAAA,EAA2B;AACrE,EAAA,IAAI,GAAA,CAAI,UAAU,SAAA,EAAW;AAC3B,IAAA,OAAO,GAAA;AAAA,EACT;AACA,EAAA,OAAO,GAAG,GAAA,CAAI,KAAA,CAAM,CAAA,EAAG,SAAA,GAAY,CAAC,CAAC,CAAA,GAAA,CAAA;AACvC;AAOO,SAAS,WAAW,GAAA,EAAqB;AAC9C,EAAA,IAAI,GAAA,CAAI,WAAW,CAAA,EAAG;AACpB,IAAA,OAAO,GAAA;AAAA,EACT;AACA,EAAA,OAAO,GAAA,CAAI,OAAO,CAAC,CAAA,CAAE,aAAY,GAAI,GAAA,CAAI,MAAM,CAAC,CAAA;AAClD;AAOO,SAAS,gBAAgB,IAAA,EAA+B;AAC7D,EAAA,MAAM,SAAS,MAAA,CAAO,IAAA,CAAK,IAAI,CAAA,CAAE,SAAS,QAAQ,CAAA;AAClD,EAAA,OAAO,MAAA,CAAO,OAAA,CAAQ,KAAA,EAAO,GAAG,CAAA,CAAE,OAAA,CAAQ,KAAA,EAAO,GAAG,CAAA,CAAE,OAAA,CAAQ,IAAA,EAAM,EAAE,CAAA;AACxE;AAOO,SAAS,gBAAgB,OAAA,EAAyB;AACvD,EAAA,MAAM,MAAA,GAAS,QAAQ,OAAA,CAAQ,IAAA,EAAM,GAAG,CAAA,CAAE,OAAA,CAAQ,MAAM,GAAG,CAAA;AAE3D,EAAA,MAAM,MAAA,GAAS,SAAS,GAAA,CAAI,MAAA,CAAA,CAAQ,IAAK,MAAA,CAAO,MAAA,GAAS,KAAM,CAAC,CAAA;AAChE,EAAA,OAAO,MAAA,CAAO,IAAA,CAAK,MAAA,EAAQ,QAAQ,CAAA;AACrC;AAOO,SAAS,iBAAiB,GAAA,EAAsB;AACrD,EAAA,MAAM,cAAA,GAAiB,kBAAA;AACvB,EAAA,OAAO,cAAA,CAAe,KAAK,GAAG,CAAA;AAChC;AA6BO,SAAS,gBAAgB,KAAA,EAAwB;AACtD,EAAA,IAAI,iBAAiB,KAAA,EAAO;AAC1B,IAAA,OAAO,KAAA,CAAM,OAAA;AAAA,EACf;AACA,EAAA,IAAI,OAAO,UAAU,QAAA,EAAU;AAC7B,IAAA,OAAO,KAAA;AAAA,EACT;AACA,EAAA,IACE,OAAO,KAAA,KAAU,QAAA,IACjB,KAAA,KAAU,IAAA,IACV,aAAa,KAAA,IACb,OAAO,KAAA,CAAM,OAAA,KAAY,QAAA,EACzB;AACA,IAAA,OAAO,KAAA,CAAM,OAAA;AAAA,EACf;AACA,EAAA,OAAO,OAAO,KAAK,CAAA;AACrB","file":"string.js","sourcesContent":["/**\n * String utility functions\n */\n\n/**\n * Check if a string is empty or only contains whitespace\n * @param value - The string to check\n * @returns true if the string is empty, null, undefined, or only whitespace\n */\nexport function isEmptyString(value: string | null | undefined): boolean {\n  return value == null || value.trim().length === 0;\n}\n\n/**\n * Check if a string is not empty and contains non-whitespace characters\n * @param value - The string to check\n * @returns true if the string has content\n */\nexport function isNonEmptyString(\n  value: string | null | undefined,\n): value is string {\n  return value != null && value.trim().length > 0;\n}\n\n/**\n * Truncate a string to a maximum length with ellipsis\n * @param str - The string to truncate\n * @param maxLength - Maximum length (including ellipsis)\n * @returns Truncated string with ellipsis if needed\n */\nexport function truncateString(str: string, maxLength: number): string {\n  if (str.length <= maxLength) {\n    return str;\n  }\n  return `${str.slice(0, maxLength - 3)}...`;\n}\n\n/**\n * Capitalize the first letter of a string\n * @param str - The string to capitalize\n * @returns String with first letter capitalized\n */\nexport function capitalize(str: string): string {\n  if (str.length === 0) {\n    return str;\n  }\n  return str.charAt(0).toUpperCase() + str.slice(1);\n}\n\n/**\n * Create a base64url encoded string\n * @param data - Data to encode (string or Buffer)\n * @returns Base64url encoded string (URL-safe, no padding)\n */\nexport function encodeBase64Url(data: string | Buffer): string {\n  const base64 = Buffer.from(data).toString(\"base64\");\n  return base64.replace(/\\+/g, \"-\").replace(/\\//g, \"_\").replace(/=/g, \"\");\n}\n\n/**\n * Decode a base64url encoded string\n * @param encoded - Base64url encoded string\n * @returns Decoded data as Buffer\n */\nexport function decodeBase64Url(encoded: string): Buffer {\n  const base64 = encoded.replace(/-/g, \"+\").replace(/_/g, \"/\");\n  // Add padding if needed\n  const padded = base64 + \"=\".repeat((4 - (base64.length % 4)) % 4);\n  return Buffer.from(padded, \"base64\");\n}\n\n/**\n * Check if a string is a valid base64url format\n * @param str - String to validate\n * @returns True if the string is valid base64url format\n */\nexport function isValidBase64Url(str: string): boolean {\n  const base64UrlRegex = /^[A-Za-z0-9_-]*$/;\n  return base64UrlRegex.test(str);\n}\n\n/**\n * Extract a message string from an unknown error value\n * @deprecated This utility is unnecessary. The logger accepts `ErrorLike` (unknown)\n * directly via `logger.error(tag, message, error)`. Pass errors directly to the\n * logger instead of manually converting to strings.\n *\n * See: docs/standards/error-boundary-patterns.md\n * @example\n * ```typescript\n * // ❌ DEPRECATED: Manual error string extraction\n * try {\n *   await operation();\n * } catch (error) {\n *   logger.error(\"Component\", getErrorMessage(error));\n * }\n *\n * // ✅ CORRECT: Pass error directly to logger\n * try {\n *   await operation();\n * } catch (error) {\n *   logger.error(\"Component\", \"Operation failed\", error);\n * }\n * ```\n * @param error - Error value (Error object, string, or other)\n * @returns Error message string\n * @internal\n */\nexport function getErrorMessage(error: unknown): string {\n  if (error instanceof Error) {\n    return error.message;\n  }\n  if (typeof error === \"string\") {\n    return error;\n  }\n  if (\n    typeof error === \"object\" &&\n    error !== null &&\n    \"message\" in error &&\n    typeof error.message === \"string\"\n  ) {\n    return error.message;\n  }\n  return String(error);\n}\n"]}

package/docs/README.md

@@ -0,0 +1,35 @@
+# @reasonabletech/utils Documentation
+
+Reference documentation for shared runtime utility helpers in the core-utils monorepo.
+
+## Start Here
+
+- [Usage Guide](./guides/usage-guide.md)
+- [Utility Function Reference](./utility-functions.md)
+
+## Quick Example
+
+```ts
+import { err, ok, type Result } from "@reasonabletech/utils";
+
+function divide(a: number, b: number): Result<number, string> {
+  if (b === 0) {
+    return err("Division by zero");
+  }
+  return ok(a / b);
+}
+
+const result = divide(10, 2);
+if (result.success) {
+  console.log("Result:", result.value);
+} else {
+  console.error("Error:", result.error);
+}
+```
+
+## Monorepo Context
+
+- [Package README](../README.md)
+- [Architecture](../../../docs/architecture.md) — How packages relate
+- [Tooling](../../../docs/tooling.md) — Turbo, Changesets details
+- [Contributing](../../../CONTRIBUTING.md)

package/docs/guides/migration.md

@@ -0,0 +1,47 @@
+# Migration Guide
+
+This guide documents breaking changes and how to migrate between major versions of @reasonabletech/utils.
+
+## Current Version
+
+The current major version is **0.x** (pre-1.0). The API is stabilizing but may have breaking changes before 1.0.
+
+## Future Migration Notes
+
+_No breaking changes documented yet. This section will be updated when breaking changes are released._
+
+---
+
+## Migration Template
+
+When documenting a breaking change, use this structure:
+
+### Migrating from X.x to Y.0
+
+#### Breaking Changes
+
+1. **Change description** - Brief explanation of what changed
+   
+   **Before:**
+   ```typescript
+   // Old usage
+   ```
+   
+   **After:**
+   ```typescript
+   // New usage
+   ```
+
+2. **Another change** - Description
+
+#### Deprecations
+
+- `oldFunction()` is deprecated in favor of `newFunction()`
+
+#### New Features
+
+- Feature description
+
+---
+
+_Last updated: [date]_

package/docs/guides/usage-guide.md

@@ -0,0 +1,99 @@
+# @reasonabletech/utils Usage Guide
+
+This guide covers canonical usage patterns for shared utility helpers in greenfield packages and applications.
+
+## Installation
+
+```bash
+pnpm add @reasonabletech/utils
+```
+
+## Quick Start
+
+```ts
+import { err, ok, type Result } from "@reasonabletech/utils";
+
+function divide(a: number, b: number): Result<number, string> {
+  if (b === 0) {
+    return err("Division by zero");
+  }
+  return ok(a / b);
+}
+```
+
+## Core Use Cases
+
+### Result-Based Error Handling
+
+```ts
+import { andThen, err, ok, type Result } from "@reasonabletech/utils";
+
+function parseId(input: string): Result<number, string> {
+  const parsed = Number(input);
+  return Number.isInteger(parsed) ? ok(parsed) : err("Invalid ID");
+}
+
+const result = andThen(parseId("42"), (id) => ok({ id }));
+```
+
+### Retry Helpers
+
+```ts
+import { retryWithBackoff } from "@reasonabletech/utils";
+
+const response = await retryWithBackoff(
+  async () => await fetch("https://api.example.com/health"),
+  3,
+  500,
+);
+```
+
+### Object Construction Helpers
+
+```ts
+import { includeIf, includeIfDefined } from "@reasonabletech/utils";
+
+const payload = {
+  name: "core-utils",
+  ...includeIf("description", process.env.PKG_DESCRIPTION),
+  ...includeIfDefined({
+    homepage: process.env.PKG_HOMEPAGE,
+    repository: process.env.PKG_REPOSITORY,
+  }),
+};
+```
+
+### Datetime + Async Helpers
+
+```ts
+import { addDays, now, pipeAsync } from "@reasonabletech/utils";
+
+const nextWeek = addDays(now(), 7);
+
+const normalized = await pipeAsync(" core-utils ", [
+  async (value) => value.trim(),
+  async (value) => value.toUpperCase(),
+]);
+```
+
+## Subpath Imports
+
+Use subpaths when you want narrower imports:
+
+- `@reasonabletech/utils/result`
+- `@reasonabletech/utils/datetime`
+- `@reasonabletech/utils/object`
+- `@reasonabletech/utils/string`
+- `@reasonabletech/utils/retry`
+
+## Troubleshooting
+
+### `Result` shape confusion
+
+The shared `Result` type uses `success` + `value`/`error` fields. Prefer helper functions (`ok`, `err`, `isSuccess`, `isFailure`) instead of creating objects manually.
+
+## Related Documentation
+
+- [Package Docs Index](../README.md)
+- [Utility Function Reference](../utility-functions.md)
+- [Package README](../../README.md)