@xeno-js/shared 0.1.0

package/dist/shared/utils/string.utils.d.ts

@@ -0,0 +1,102 @@
+import type { Dictionary, Optional } from '../types/index';
+/**
+ * @description Namespace for string manipulation utilities.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+export declare const StringHelper: Readonly<{
+    /**
+     * @description Safely converts a value to a JSON string, falling back to String() on failure.
+     * @param value The value to stringify.
+     * @returns A JSON string representation of the value, or a fallback string if serialization fails.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    readonly safeStringify: <T>(value: T) => string;
+    /**
+     * @description Safely parses a JSON string, returning a fallback value on failure.
+     * @param input The JSON string to parse.
+     * @param fallback Optional fallback value to return if parsing fails.
+     * @returns The parsed value, or the fallback value if parsing fails.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    readonly safeParse: <T = unknown>(input: string, fallback?: Optional<T>) => T | Optional<string>;
+    /**
+     * @description Converts a string to camelCase.
+     * @param input Input string (supports snake_case, kebab-case, or space-separated).
+     * @returns camelCase string.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    readonly camelCase: (input: string) => string;
+    /**
+     * @description Interpolates {{key}} placeholders in a template string.
+     * @param template Template string with {{key}} tokens.
+     * @param vars Key-value substitution map.
+     * @returns Interpolated string with resolved placeholders.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    readonly interpolate: (template: string, vars: Readonly<Dictionary<string | number>>) => string;
+    /**
+     * @description Truncates a string to maxLength, appending a suffix when truncated.
+     * @param input Input string.
+     * @param maxLength Maximum character length including the suffix.
+     * @param suffix Appended suffix on truncation.
+     * @returns Truncated string.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    readonly truncate: (input: string, maxLength: number, suffix?: string) => string;
+    /**
+     * @description Generates a reference code with a prefix, random alphanumeric part, and year.
+     * @param prefix Custom prefix for the reference code (e.g., "TRV" for travel).
+     * @returns Formatted reference code string.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    readonly generateReferenceCode: (prefix: string) => string;
+    /**
+     * @description Extracts a single string value from a header that may be a string or an array of strings.
+     * @param value The header value, which can be a string or an array of strings.
+     * @returns The first string value if it's an array, the string itself if it's a string, or undefined if it's empty or not defined.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    readonly getSingleValue: (value: Optional<string | string[]>, separator?: Optional<string>) => Optional<string>;
+    readonly getSingleValueWithSplit: (value: string, separator: string) => string;
+}>;
+//# sourceMappingURL=string.utils.d.ts.map

package/dist/shared/utils/string.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"string.utils.d.ts","sourceRoot":"","sources":["../../../src/shared/utils/string.utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAG1D;;;;;;;;KAQK;AACL,eAAO,MAAM,YAAY;IACvB;;;;;;;;;;OAUG;6BACW,CAAC,SAAS,CAAC,KAAG,MAAM;IAQlC;;;;;;;;;;;OAWG;yBACO,CAAC,mBAAmB,MAAM,aAAY,QAAQ,CAAC,CAAC,CAAC,KAAe,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC;IAQ9F;;;;;;;;;;OAUG;gCACc,MAAM,KAAG,MAAM;IAOhC;;;;;;;;;;;OAWG;qCACmB,MAAM,QAAQ,QAAQ,CAAC,UAAU,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,KAAG,MAAM;IAOlF;;;;;;;;;;;;OAYG;+BACa,MAAM,aAAa,MAAM,sBAAiB,MAAM;IAMhE;;;;;;;;;;OAUG;6CAC2B,MAAM,KAAG,MAAM;IAU7C;;;;;;;;;;OAUG;qCAEM,QAAQ,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC,cACtB,QAAQ,CAAC,MAAM,CAAC,KAC3B,QAAQ,CAAC,MAAM,CAAC;8CAeY,MAAM,aAAa,MAAM,KAAG,MAAM;EAIxD,CAAA"}

package/dist/shared/utils/string.utils.js

@@ -0,0 +1,157 @@
+import { Guards } from './guards.utils';
+/**
+ * @description Namespace for string manipulation utilities.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+export const StringHelper = Object.freeze({
+    /**
+     * @description Safely converts a value to a JSON string, falling back to String() on failure.
+     * @param value The value to stringify.
+     * @returns A JSON string representation of the value, or a fallback string if serialization fails.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    safeStringify(value) {
+        try {
+            return JSON.stringify(value);
+        }
+        catch {
+            return String(value);
+        }
+    },
+    /**
+     * @description Safely parses a JSON string, returning a fallback value on failure.
+     * @param input The JSON string to parse.
+     * @param fallback Optional fallback value to return if parsing fails.
+     * @returns The parsed value, or the fallback value if parsing fails.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    safeParse(input, fallback = undefined) {
+        try {
+            return JSON.parse(input);
+        }
+        catch {
+            return fallback ?? input;
+        }
+    },
+    /**
+     * @description Converts a string to camelCase.
+     * @param input Input string (supports snake_case, kebab-case, or space-separated).
+     * @returns camelCase string.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    camelCase(input) {
+        const segments = input.split(/[-_\s]+/);
+        const [first, ...rest] = segments;
+        const head = Guards.isDefined(first) ? first.toLowerCase() : '';
+        return head + rest.map((seg) => seg.charAt(0).toUpperCase() + seg.slice(1)).join('');
+    },
+    /**
+     * @description Interpolates {{key}} placeholders in a template string.
+     * @param template Template string with {{key}} tokens.
+     * @param vars Key-value substitution map.
+     * @returns Interpolated string with resolved placeholders.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    interpolate(template, vars) {
+        return template.replace(/\{\{(\w+)\}\}/g, (_match, key) => {
+            const value = vars[key];
+            return Guards.isDefined(value) ? String(value) : `{{${key}}}`;
+        });
+    },
+    /**
+     * @description Truncates a string to maxLength, appending a suffix when truncated.
+     * @param input Input string.
+     * @param maxLength Maximum character length including the suffix.
+     * @param suffix Appended suffix on truncation.
+     * @returns Truncated string.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    truncate(input, maxLength, suffix = '…') {
+        if (input.length <= maxLength)
+            return input;
+        const cutAt = Math.max(0, maxLength - suffix.length);
+        return input.slice(0, cutAt) + suffix;
+    },
+    /**
+     * @description Generates a reference code with a prefix, random alphanumeric part, and year.
+     * @param prefix Custom prefix for the reference code (e.g., "TRV" for travel).
+     * @returns Formatted reference code string.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    generateReferenceCode(prefix) {
+        const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+        let randomPart = '';
+        for (let i = 0; i < 6; i++) {
+            randomPart += chars.charAt(Math.floor(Math.random() * chars.length));
+        }
+        const year = new Date().getFullYear();
+        return `${prefix}-${randomPart}-${year}`; // Es: TRV-XJ82L9-2026
+    },
+    /**
+     * @description Extracts a single string value from a header that may be a string or an array of strings.
+     * @param value The header value, which can be a string or an array of strings.
+     * @returns The first string value if it's an array, the string itself if it's a string, or undefined if it's empty or not defined.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    getSingleValue(value, separator) {
+        if (!Guards.isDefined(value))
+            return value;
+        if (Guards.isArray(value)) {
+            if (Guards.isNullOrEmpty(value)) {
+                return undefined;
+            }
+            if (Guards.isDefined(separator))
+                return StringHelper.getSingleValueWithSplit(value[0], separator);
+            return value[0];
+        }
+        if (Guards.isDefined(separator))
+            return StringHelper.getSingleValueWithSplit(value, separator);
+        return value;
+    },
+    getSingleValueWithSplit(value, separator) {
+        if (value.includes(separator))
+            return value.split(separator)[0].trim();
+        return value;
+    },
+});
+//# sourceMappingURL=string.utils.js.map

package/dist/shared/utils/string.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"string.utils.js","sourceRoot":"","sources":["../../../src/shared/utils/string.utils.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAEvC;;;;;;;;KAQK;AACL,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC;IACxC;;;;;;;;;;OAUG;IACH,aAAa,CAAI,KAAQ;QACvB,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;QAC9B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,MAAM,CAAC,KAAK,CAAC,CAAA;QACtB,CAAC;IACH,CAAC;IAED;;;;;;;;;;;OAWG;IACH,SAAS,CAAc,KAAa,EAAE,WAAwB,SAAS;QACrE,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAM,CAAA;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,QAAQ,IAAI,KAAK,CAAA;QAC1B,CAAC;IACH,CAAC;IAED;;;;;;;;;;OAUG;IACH,SAAS,CAAC,KAAa;QACrB,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAA;QACvC,MAAM,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,GAAG,QAAQ,CAAA;QACjC,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;QAC/D,OAAO,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IACtF,CAAC;IAED;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,QAAgB,EAAE,IAA2C;QACvE,OAAO,QAAQ,CAAC,OAAO,CAAC,gBAAgB,EAAE,CAAC,MAAM,EAAE,GAAW,EAAE,EAAE;YAChE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAA;YACvB,OAAO,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,CAAA;QAC/D,CAAC,CAAC,CAAA;IACJ,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,KAAa,EAAE,SAAiB,EAAE,MAAM,GAAG,GAAG;QACrD,IAAI,KAAK,CAAC,MAAM,IAAI,SAAS;YAAE,OAAO,KAAK,CAAA;QAC3C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,CAAA;QACpD,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,MAAM,CAAA;IACvC,CAAC;IAED;;;;;;;;;;OAUG;IACH,qBAAqB,CAAC,MAAc;QAClC,MAAM,KAAK,GAAG,sCAAsC,CAAA;QACpD,IAAI,UAAU,GAAG,EAAE,CAAA;QACnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC3B,UAAU,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAA;QACtE,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;QACrC,OAAO,GAAG,MAAM,IAAI,UAAU,IAAI,IAAI,EAAE,CAAA,CAAC,sBAAsB;IACjE,CAAC;IAED;;;;;;;;;;OAUG;IACH,cAAc,CACZ,KAAkC,EAClC,SAA4B;QAE5B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAA;QAE1C,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1B,IAAI,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;gBAChC,OAAO,SAAS,CAAA;YAClB,CAAC;YACD,IAAI,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC;gBAC7B,OAAO,YAAY,CAAC,uBAAuB,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,CAAA;YAClE,OAAO,KAAK,CAAC,CAAC,CAAC,CAAA;QACjB,CAAC;QACD,IAAI,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC;YAAE,OAAO,YAAY,CAAC,uBAAuB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAA;QAC9F,OAAO,KAAK,CAAA;IACd,CAAC;IAED,uBAAuB,CAAC,KAAa,EAAE,SAAiB;QACtD,IAAI,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC;YAAE,OAAO,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;QACtE,OAAO,KAAK,CAAA;IACd,CAAC;CACO,CAAC,CAAA"}

package/package.json

@@ -0,0 +1,111 @@
+{
+  "name": "@xeno-js/shared",
+  "version": "0.1.0",
+  "description": "Xeno shared npm package",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xeno-js/xeno-shared.git"
+  },
+  "bugs": {
+    "url": "https://github.com/xeno-js/xeno-shared/issues"
+  },
+  "homepage": "https://github.com/xeno-js/xeno-shared#readme",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && tsc-alias",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint --config eslint.config.mjs \"src/**/*.ts\" --max-warnings=0",
+    "lint:fix": "eslint --config eslint.config.mjs \"src/**/*.ts\" --fix --max-warnings=0",
+    "lint-staged": "lint-staged",
+    "commitlint": "commitlint",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "check": "npm run typecheck && npm run lint:fix && npm run test",
+    "verify:commit": "npm run lint-staged && npm run test",
+    "verify:push": "npm run check",
+    "prepare": "husky",
+    "prepublishOnly": "npm run check && npm run build",
+    "release": "npm run prepublishOnly && npm publish"
+  },
+  "keywords": [
+    "ddd",
+    "clean-architecture",
+    "core",
+    "kernel",
+    "domain-driven-design",
+    "mediator",
+    "event-sourcing",
+    "cqrs",
+    "repository-pattern",
+    "supabase",
+    "zod"
+  ],
+  "author": "Xeno",
+  "license": "ISC",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "peerDependencies": {
+    "@supabase/supabase-js": "^2.112.4",
+    "axios": "^1.16.1",
+    "cockatiel": "^4.0.0",
+    "zod": "^4.4.3"
+  },
+  "peerDependenciesMeta": {
+    "@supabase/supabase-js": {
+      "optional": true
+    },
+    "axios": {
+      "optional": true
+    },
+    "cockatiel": {
+      "optional": true
+    },
+    "zod": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^21.0.1",
+    "@commitlint/config-conventional": "^21.0.1",
+    "@eslint/js": "^10.0.1",
+    "@supabase/supabase-js": "^2.112.4",
+    "@types/pg": "^8.20.0",
+    "@vitest/coverage-v8": "^4.1.7",
+    "axios": "^1.16.1",
+    "cockatiel": "^4.0.0",
+    "eslint": "^10.4.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-simple-import-sort": "^13.0.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.0.5",
+    "prettier": "^3.8.3",
+    "tsc-alias": "^1.9.2",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.60.0",
+    "vitest": "^4.1.7",
+    "zod": "^4.4.3"
+  },
+  "overrides": {
+    "esbuild": "^0.25.0"
+  }
+}