@reliverse/utils 2.3.0

package/dist/mod.d.ts

@@ -0,0 +1 @@
+export * from "./validation.js.js";

package/dist/mod.js

@@ -0,0 +1 @@
+export * from "./validation.js";

package/dist/validation.d.ts

@@ -0,0 +1,56 @@
+import { type } from "arktype";
+/**
+ * Common validation utilities using arktype for consistent error handling
+ * and type safety across the codebase.
+ */
+/**
+ * File path validation with safety checks
+ */
+export declare const SafePath: import("arktype/out/variants/string").StringType<string, {}>;
+/**
+ * URL validation with protocol checking
+ */
+export declare const SafeUrl: import("arktype/out/variants/string").StringType<string, {}>;
+/**
+ * Email validation using arktype built-in constraints
+ */
+export declare const Email: import("arktype/out/variants/string").StringType<string, {}>;
+/**
+ * Port number validation with common service warnings
+ */
+export declare const Port: import("arktype/out/variants/number").NumberType<number, {}>;
+/**
+ * Semver validation using arktype built-in constraints
+ */
+export declare const Semver: import("arktype/out/variants/string").StringType<string, {}>;
+/**
+ * Non-empty string validation
+ */
+export declare const NonEmptyString: import("arktype/out/variants/string").StringType<string, {}>;
+/**
+ * Positive integer validation
+ */
+export declare const PositiveInteger: import("arktype/out/variants/number").NumberType<number, {}>;
+/**
+ * Creates a validated array with minimum and maximum length constraints
+ */
+export declare const createConstrainedArray: (itemType: "string" | "number" | "boolean", constraints?: {
+    minLength?: number;
+    maxLength?: number;
+}) => import("arktype/out/variants/array").ArrayType<(string | number | boolean)[], {}>;
+/**
+ * Creates a union type with custom error messages
+ */
+export declare const createUnionWithMessages: <T extends readonly [string, ...string[]]>(literals: T, descriptions?: Record<string, string>) => import("arktype").BaseType<any, {}>;
+/**
+ * Creates a morph that transforms data with validation
+ */
+export declare const createSafeMorph: <In, Out>(transformer: (input: In) => Out | Error, errorMessage?: string) => (input: In) => Out;
+/**
+ * Type guard helper for arktype validation results
+ */
+export declare const isValid: <T>(result: T | type.errors) => result is T;
+/**
+ * Type assertion helper that throws on validation failure
+ */
+export declare const assertValid: <T>(result: T | type.errors, context?: string) => T;

package/dist/validation.js

@@ -0,0 +1,123 @@
+import { type } from "arktype";
+export const SafePath = type("string").configure({
+  description: "a safe file path"
+}).narrow((path, ctx) => {
+  if (!path.trim()) {
+    return ctx.reject("path cannot be empty or only whitespace");
+  }
+  if (path.includes("../") || path.includes("..\\")) {
+    return ctx.reject("path contains directory traversal which is not allowed");
+  }
+  if (path.startsWith("/")) {
+    console.warn("absolute paths may not work across different environments");
+  }
+  return true;
+});
+export const SafeUrl = type("string").configure({
+  description: "a valid URL with allowed protocols"
+}).narrow((url, ctx) => {
+  try {
+    const parsed = new URL(url);
+    const allowedProtocols = ["http:", "https:", "ftp:"];
+    if (!allowedProtocols.includes(parsed.protocol)) {
+      return ctx.reject({
+        expected: `URL with protocol: ${allowedProtocols.join(", ")}`,
+        actual: parsed.protocol
+      });
+    }
+    return true;
+  } catch {
+    return ctx.reject("invalid URL format");
+  }
+});
+export const Email = type("string.email").configure({
+  description: "a valid email address"
+});
+export const Port = type("number.integer > 0 & number.integer < 65536").configure({
+  description: "a valid port number"
+}).narrow((port) => {
+  const commonPorts = {
+    22: "SSH",
+    25: "SMTP",
+    53: "DNS",
+    80: "HTTP",
+    110: "POP3",
+    143: "IMAP",
+    443: "HTTPS",
+    993: "IMAPS",
+    995: "POP3S",
+    3306: "MySQL",
+    5432: "PostgreSQL",
+    6379: "Redis",
+    8080: "HTTP Alt",
+    8443: "HTTPS Alt"
+  };
+  if (commonPorts[port]) {
+    console.warn(`Port ${port} is commonly used by ${commonPorts[port]} - potential conflicts`);
+  }
+  return true;
+});
+export const Semver = type("string.semver").configure({
+  description: "a valid semantic version"
+}).narrow((version) => {
+  if (version.includes("-")) {
+    console.warn("pre-release version detected - ensure compatibility requirements");
+  }
+  return true;
+});
+export const NonEmptyString = type("string").configure({
+  description: "a non-empty string"
+}).narrow((str, ctx) => {
+  return str.trim().length > 0 || ctx.reject("string cannot be empty or only whitespace");
+});
+export const PositiveInteger = type("number.integer > 0").configure({
+  description: "a positive integer"
+});
+export const createConstrainedArray = (itemType, constraints = {}) => {
+  const { minLength, maxLength } = constraints;
+  return type(itemType).array().configure({
+    description: `array of items${minLength ? ` (min ${minLength})` : ""}${maxLength ? ` (max ${maxLength})` : ""}`
+  }).narrow((arr, ctx) => {
+    if (minLength && arr.length < minLength) {
+      return ctx.reject(`array must have at least ${minLength} items`);
+    }
+    if (maxLength && arr.length > maxLength) {
+      return ctx.reject(`array must have at most ${maxLength} items`);
+    }
+    return true;
+  });
+};
+export const createUnionWithMessages = (literals, descriptions) => {
+  const unionString = literals.map((l) => `'${l}'`).join(" | ");
+  return type(unionString).configure({
+    description: descriptions ? Object.values(descriptions).join(" | ") : `one of: ${literals.join(", ")}`
+  }).narrow((value, ctx) => {
+    if (!literals.includes(value)) {
+      const expected = descriptions ? Object.entries(descriptions).map(([k, v]) => `${k}: ${v}`).join(", ") : literals.join(", ");
+      return ctx.reject({
+        expected: `one of: ${expected}`,
+        actual: value
+      });
+    }
+    return true;
+  });
+};
+export const createSafeMorph = (transformer, errorMessage) => {
+  return (input) => {
+    const result = transformer(input);
+    if (result instanceof Error) {
+      throw new Error(errorMessage || result.message);
+    }
+    return result;
+  };
+};
+export const isValid = (result) => {
+  return !(result instanceof type.errors);
+};
+export const assertValid = (result, context) => {
+  if (result instanceof type.errors) {
+    const message = context ? `${context}: ${result.summary}` : result.summary;
+    throw new Error(message);
+  }
+  return result;
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@reliverse/utils",
+  "version": "2.3.0",
+  "description": "Shared utilities for Reliverse packages",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.d.ts",
+      "default": "./dist/mod.js"
+    },
+    "./validation": {
+      "types": "./dist/validation.d.d.ts",
+      "default": "./dist/validation.js"
+    }
+  },
+  "dependencies": {
+    "arktype": "^2.1.29"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.9.3"
+  },
+  "files": [
+    "dist",
+    "package.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}