feat: add separate utilities package with parse function

.gitignore

@@ -1,6 +1,7 @@
+**/coverage
+**/dist
 **/.env*
 !**/.env.example
-**/dist
 **/*.log*
 **/node_modules
 .turbo

package.json

@@ -16,6 +16,7 @@
     "build": "turbo run build",
     "lint": "turbo run lint",
     "lint:fix": "turbo run lint:fix",
+    "lint:md": "pnpx prettier --write '*.md' 'docs/**/*.md' '.claude/**/*.md'",
     "prepare": "husky",
     "publish": "npx shipjs trigger",
     "release": "npx shipjs prepare",

packages/utilities/README.md

@@ -0,0 +1,15 @@
+# @prefabs.tech/utilities
+
+A collection of common utility functions for projects.
+
+## Install
+
+```sh
+npm i @prefabs.tech/utilities
+```
+
+## Available Utilities
+
+### `parse(value, fallback?)`
+
+Parses a value with optional type-safe fallback. Useful for parsing environment variables and configuration values.

packages/utilities/eslint.config.js

@@ -0,0 +1,3 @@
+import eslintConfig from "@prefabs.tech/eslint-config/index.js";
+
+export default [...eslintConfig];

packages/utilities/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@prefabs.tech/utilities",
+  "version": "0.7.0",
+  "description": "Utilities",
+  "homepage": "https://github.com/prefabs-tech/tools/tree/main/packages/utilities#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/prefabs-tech/tools.git",
+    "directory": "packages/utilities"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/PrefabsTechToolsUtilities.es.js",
+      "require": "./dist/PrefabsTechToolsUtilities.umd.js"
+    }
+  },
+  "main": "./dist/PrefabsTechToolsUtilities.umd.js",
+  "module": "./dist/PrefabsTechToolsUtilities.es.js",
+  "types": "./dist/src/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build && tsc --emitDeclarationOnly",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest --environment jsdom run --coverage --passWithNoTests",
+    "test:unit": "vitest --environment jsdom run unit/ --passWithNoTests",
+    "typecheck": "tsc --noEmit -p tsconfig.vitest.json --composite false"
+  },
+  "devDependencies": {
+    "@prefabs.tech/eslint-config": "0.7.0",
+    "@prefabs.tech/tsconfig": "0.7.0",
+    "@types/node": "25.3.5",
+    "@vitest/coverage-v8": "4.1.5",
+    "eslint": "9.39.4",
+    "jsdom": "29.1.1",
+    "typescript": "5.9.3",
+    "vite": "7.3.2",
+    "vitest": "4.1.5"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

packages/utilities/src/__test__/unit/parse.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+
+import { parse } from "../../parse";
+
+describe("parse", () => {
+  it("Returns fallback value if value is undefined", () => {
+    expect(parse(undefined, 3n)).toBe(3n);
+  });
+
+  it("Returns value if the value is boolean", () => {
+    expect(parse(false, "fallback")).toBe(false);
+  });
+
+  it("Parse string to boolean", () => {
+    expect(parse("false", true)).toBe(false);
+    expect(parse("true", false)).toBe(true);
+  });
+
+  it("Parse string to int if the fallback have type int", () => {
+    expect(parse("100", 50)).toBe(100);
+    expect(parse("546", 50)).toBe(546);
+  });
+
+  it("Check if the value is returned if there is no fallback", () => {
+    expect(parse(34)).toBe(34);
+    expect(parse("PARSE")).toBe("PARSE");
+  });
+});

packages/utilities/src/index.ts

@@ -0,0 +1 @@
+export { parse } from "./parse";

packages/utilities/src/parse.ts

@@ -0,0 +1,26 @@
+export const parse = (
+  value: boolean | number | string | undefined,
+  fallback?: bigint | boolean | null | number | string,
+) => {
+  if (value === undefined) {
+    return fallback;
+  }
+
+  if (typeof value === "boolean") {
+    return value;
+  }
+
+  switch (typeof fallback) {
+    case "boolean": {
+      return !!JSON.parse(value as string);
+    }
+
+    case "number": {
+      return JSON.parse(value as string);
+    }
+
+    default: {
+      return value;
+    }
+  }
+};

packages/utilities/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "@prefabs.tech/tsconfig/tsconfig.json",
+  "compilerOptions": {
+    "moduleResolution": "bundler",
+    "outDir": "./dist",
+    "paths": {
+      "@/*": ["./src/*"]
+    },
+  },
+  "include": ["src/**/*"]
+}

packages/utilities/tsconfig.vitest.json

@@ -0,0 +1,7 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "composite": false
+  },
+  "include": ["src/**/*", "test/**/*"]
+}

packages/utilities/vite.config.ts

@@ -0,0 +1,24 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { defineConfig, loadEnv } from "vite";
+
+// https://vitejs.dev/config/
+export default defineConfig(({ mode }) => {
+  process.env = { ...process.env, ...loadEnv(mode, process.cwd()) };
+
+  return {
+    build: {
+      lib: {
+        entry: resolve(dirname(fileURLToPath(import.meta.url)), "src/index.ts"),
+        fileName: (format) => `PrefabsTechToolsUtilities.${format}.js`,
+        name: "PrefabsTechToolsUtilities",
+      },
+      target: "esnext",
+    },
+    resolve: {
+      alias: {
+        "@": new URL("src/", import.meta.url).pathname,
+      },
+    },
+  };
+});

packages/utilities/vitest.config.ts

@@ -0,0 +1,19 @@
+import { mergeConfig } from "vite";
+import { defineConfig } from "vitest/config";
+
+import viteConfig from "./vite.config";
+
+export default defineConfig((configEnvironment) =>
+  mergeConfig(
+    viteConfig(configEnvironment),
+    defineConfig({
+      test: {
+        coverage: {
+          reporter: ["text", "json", "html"],
+        },
+        environment: "jsdom",
+        globals: true,
+      },
+    }),
+  ),
+);