@togatherlabs/shared-utils 1.0.0 → 1.0.2

package/README.md

@@ -1 +1,175 @@
-# togather-shared-utils
+# @togatherlabs/shared-utils
+
+A collection of **shared TypeScript utilities, constants, and types** used across ToGather microservices.
+
+[![npm package](https://img.shields.io/npm/v/@togatherlabs/shared-utils.svg)](https://www.npmjs.com/package/@togatherlabs/shared-utils)
+[![npm downloads](https://img.shields.io/npm/dm/@togatherlabs/shared-utils.svg)](https://www.npmjs.com/package/@togatherlabs/shared-utils)
+[![license](https://img.shields.io/npm/l/@togatherlabs/shared-utils.svg)](./LICENSE)
+
+## Table of Contents
+
+1. [Directory Structure](#directory-structure)
+2. [Package Development](#package-development)
+
+   * [Adding New Utilities](#adding-new-utilities)
+   * [Linting](#linting)
+   * [Building](#building)
+   * [Publishing Package](#publishing-package)
+3. [Using the Utilities](#using-the-utilities)
+
+   * [TypeScript](#typescript)
+4. [Best Practices](#best-practices)
+5. [Troubleshooting](#troubleshooting)
+6. [License](#license)
+
+## Directory Structure
+
+The package follows a **clear folder structure** for maintainability:
+
+```
+src/
+├── constants/
+│   └── index.ts
+├── utils/
+│   └── index.ts
+├── types/
+│   └── index.ts
+└── index.ts
+```
+
+* **constants**: Shared constants across services
+* **utils**: Reusable utility functions
+* **types**: Shared TypeScript types and interfaces
+* **index.ts**: Exports all public utilities
+
+## Package Development
+
+### Adding New Utilities
+
+1. Add your function, constant, or type in the appropriate folder (`utils`, `constants`, or `types`).
+2. Export it from the folder’s `index.ts`.
+3. Re-export from the root `index.ts` for public usage.
+
+**Example:** Adding a new utility `capitalize`:
+
+```ts
+// src/utils/capitalize.ts
+export function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+// src/utils/index.ts
+export * from './capitalize';
+
+// src/index.ts
+export * from './utils';
+```
+
+### Linting
+
+Check code style and catch errors using Biome:
+
+```bash
+pnpm lint
+pnpm lint:fix
+```
+
+### Building
+
+Compile TypeScript into the `dist/` folder:
+
+```bash
+pnpm build
+```
+
+Check types without generating output:
+
+```bash
+pnpm typecheck
+```
+
+### Publishing Package
+
+To publish the package to npm:
+
+```bash
+pnpm run release
+```
+
+This script performs:
+
+* Builds the package
+* Commits changes
+* Updates version (patch/minor/major)
+* Publishes to npm with public access
+
+Ensure all changes are committed and tests pass before publishing.
+
+## Using the Utilities
+
+### TypeScript
+
+Install the package:
+
+```bash
+pnpm add @togatherlabs/shared-utils
+```
+
+Example usage:
+
+```ts
+import { formatDate, generateId, logger } from '@togatherlabs/shared-utils';
+
+// Format a date
+console.log(formatDate(new Date()));
+
+// Generate a unique ID
+const id = generateId();
+console.log(id);
+
+// Log messages
+logger.info('Service started');
+logger.error('Failed to fetch data', { error: new Error('Network error') });
+```
+
+## Best Practices
+
+* Keep utilities small and focused – each function should have a single responsibility.
+* Type safety – use TypeScript types/interfaces, avoid `any`.
+* Documentation – add JSDoc comments for each utility.
+* Testing – write unit tests for every new utility.
+* Consistent exports – always export utilities through `index.ts` files.
+
+## Troubleshooting
+
+**Cannot find module '@togatherlabs/shared-utils'**
+
+* Ensure the package is installed
+* Check `tsconfig.json` paths if using path aliases
+* Delete `node_modules` and reinstall dependencies
+
+**Property 'myFunction' does not exist**
+
+* Ensure the function is exported correctly
+* Verify the import path matches the package export
+
+**Build errors**
+
+* Check for missing peer dependencies
+* Ensure relative imports are correct
+* Clean and rebuild the project
+
+**Version mismatches across services**
+
+* Make sure all services use compatible versions of shared-utils
+* Check changelog for breaking changes
+
+**TypeScript declaration errors**
+
+* Ensure `declaration: true` is set in `tsconfig.json`
+* Verify the `types` field in `package.json` points to the correct declaration file
+* Run `pnpm build` to regenerate type definitions
+
+## License
+
+MIT © ToGather Labs

package/dist/commitlint.config.d.ts

@@ -1,3 +1,3 @@
-import type { UserConfig } from '@commitlint/types';
+import type { UserConfig } from "@commitlint/types";
 declare const config: UserConfig;
 export default config;

package/dist/commitlint.config.js

@@ -1,89 +1,89 @@
 // This config follows the project guidelines
 // (https://docs.google.com/document/d/1psbMtN-PIF4oBbNc_pW_mtDPPAa_yPdV_apf-wq5spM/edit?tab=t.0)
 const config = {
-    extends: ['@commitlint/config-conventional'],
+    extends: ["@commitlint/config-conventional"],
     rules: {
-        'scope-empty': [2, 'never'],
-        'scope-max-length': [2, 'always', 20],
+        "scope-empty": [2, "never"],
+        "scope-max-length": [2, "always", 20],
         // Subject rules
-        'subject-max-length': [2, 'always', 50],
-        'subject-case': [2, 'always', 'sentence-case'],
-        'subject-full-stop': [2, 'never', '.'],
+        "subject-max-length": [2, "always", 50],
+        "subject-case": [2, "always", "sentence-case"],
+        "subject-full-stop": [2, "never", "."],
         // Body rules
-        'body-empty': [0],
-        'body-max-line-length': [2, 'always', 72],
+        "body-empty": [0],
+        "body-max-line-length": [2, "always", 72],
         // Footer (optional)
-        'footer-max-line-length': [2, 'always', 72],
+        "footer-max-line-length": [2, "always", 72],
     },
     prompt: {
         settings: {
             enableMultipleScopes: false,
         },
         messages: {
-            skip: ':skip (press enter to skip)',
-            max: 'Max %d characters',
-            min: 'Min %d characters',
-            emptyWarning: 'This field cannot be empty',
-            upperLimitWarning: 'Character limit exceeded',
-            lowerLimitWarning: 'Too few characters',
+            skip: ":skip (press enter to skip)",
+            max: "Max %d characters",
+            min: "Min %d characters",
+            emptyWarning: "This field cannot be empty",
+            upperLimitWarning: "Character limit exceeded",
+            lowerLimitWarning: "Too few characters",
         },
         questions: {
             type: {
                 description: "Select the type of change you're committing:",
                 enum: {
                     feat: {
-                        description: '✨ A new feature',
-                        title: 'Feature',
-                        emoji: '✨',
+                        description: "✨ A new feature",
+                        title: "Feature",
+                        emoji: "✨",
                     },
                     fix: {
-                        description: '🐛 A bug fix',
-                        title: 'Bug Fix',
-                        emoji: '🐛',
+                        description: "🐛 A bug fix",
+                        title: "Bug Fix",
+                        emoji: "🐛",
                     },
                     docs: {
-                        description: '📚 Documentation only changes',
-                        title: 'Documentation',
-                        emoji: '📚',
+                        description: "📚 Documentation only changes",
+                        title: "Documentation",
+                        emoji: "📚",
                     },
                     style: {
-                        description: '💅 Changes that do not affect code meaning (formatting, etc.)',
-                        title: 'Style',
-                        emoji: '💅',
+                        description: "💅 Changes that do not affect code meaning (formatting, etc.)",
+                        title: "Style",
+                        emoji: "💅",
                     },
                     refactor: {
-                        description: '🔧 Code change that neither fixes a bug nor adds a feature',
-                        title: 'Refactor',
-                        emoji: '🔧',
+                        description: "🔧 Code change that neither fixes a bug nor adds a feature",
+                        title: "Refactor",
+                        emoji: "🔧",
                     },
                     test: {
-                        description: '✅ Adding or updating tests',
-                        title: 'Test',
-                        emoji: '✅',
+                        description: "✅ Adding or updating tests",
+                        title: "Test",
+                        emoji: "✅",
                     },
                     chore: {
-                        description: '🛠  Maintenance tasks (e.g., tooling, dependencies)',
-                        title: 'Chore',
-                        emoji: '🛠',
+                        description: "🛠  Maintenance tasks (e.g., tooling, dependencies)",
+                        title: "Chore",
+                        emoji: "🛠",
                     },
-                    perf: { description: '⚡ Performance improvement', title: 'Performance', emoji: '⚡' },
+                    perf: { description: "⚡ Performance improvement", title: "Performance", emoji: "⚡" },
                     build: {
-                        description: '🏗 Build system or dependency changes',
-                        title: 'Build',
-                        emoji: '🏗',
+                        description: "🏗 Build system or dependency changes",
+                        title: "Build",
+                        emoji: "🏗",
                     },
-                    ci: { description: '🔁 CI/CD configuration', title: 'CI', emoji: '🔁' },
-                    revert: { description: '⏪ Reverts a previous commit', title: 'Revert', emoji: '⏪' },
+                    ci: { description: "🔁 CI/CD configuration", title: "CI", emoji: "🔁" },
+                    revert: { description: "⏪ Reverts a previous commit", title: "Revert", emoji: "⏪" },
                 },
             },
             scope: {
-                description: 'Scope of this change (e.g., auth, ui, api)',
+                description: "Scope of this change (e.g., auth, ui, api)",
             },
             subject: {
-                description: 'Write a short, imperative description (max 50 chars, e.g., Add login validation)',
+                description: "Write a short, imperative description (max 50 chars, e.g., Add login validation)",
             },
             body: {
-                description: 'Provide a detailed description of what changed, why, and how (optional)',
+                description: "Provide a detailed description of what changed, why, and how (optional)",
             },
         },
     },

package/dist/src/constants/index.d.ts

@@ -1 +1 @@
-export * from './sample';
+export * from "./sample";

package/dist/src/constants/index.js

@@ -1 +1 @@
-export * from './sample';
+export * from "./sample";

package/dist/src/constants/sample.js

@@ -1,3 +1,3 @@
 export const SAMPLE = {
-    Char: 'A'
+    Char: "A",
 };

package/dist/src/helpers/formatDate.js

@@ -1,10 +1,10 @@
-export function formatDate(date, locale = 'en-IN') {
-    if (!(date instanceof Date) || isNaN(date.getTime())) {
-        throw new Error('Invalid Date');
+export function formatDate(date, locale = "en-IN") {
+    if (!(date instanceof Date) || Number.isNaN(date.getTime())) {
+        throw new Error("Invalid Date");
     }
     return date.toLocaleDateString(locale, {
-        year: 'numeric',
-        month: 'short',
-        day: 'numeric',
+        year: "numeric",
+        month: "short",
+        day: "numeric",
     });
 }

package/dist/src/helpers/index.d.ts

@@ -1 +1 @@
-export * from './formatDate';
+export * from "./formatDate";

package/dist/src/helpers/index.js

@@ -1 +1 @@
-export * from './formatDate';
+export * from "./formatDate";

package/dist/src/index.d.ts

@@ -1,3 +1,3 @@
-export * from './helpers';
-export * from './constants';
-export * from './types';
+export * from "./constants";
+export * from "./helpers";
+export * from "./types";

package/dist/src/index.js

@@ -1,3 +1,3 @@
-export * from './helpers';
-export * from './constants';
-export * from './types';
+export * from "./constants";
+export * from "./helpers";
+export * from "./types";

package/dist/src/types/index.d.ts

@@ -1 +1 @@
-export * from './user';
+export * from "./user";

package/dist/src/types/index.js

@@ -1 +1 @@
-export * from './user';
+export * from "./user";

package/dist/tests/unit/constants/sample.test.js

@@ -1,7 +1,7 @@
-import { describe, it, expect } from 'vitest';
-import * as constants from '../../../src/constants/sample';
-describe('sample constants', () => {
-    it('should export constants correctly', () => {
+import { describe, expect, it } from "vitest";
+import * as constants from "../../../src/constants/sample";
+describe("sample constants", () => {
+    it("should export constants correctly", () => {
         expect(constants).toBeDefined();
     });
 });

package/dist/tests/unit/helpers/formatDate.test.js

@@ -1,18 +1,18 @@
-import { describe, it, expect } from 'vitest';
-import { formatDate } from '../../../src/helpers/formatDate';
-describe('formatDate helper', () => {
-    it('should format a valid date correctly', () => {
-        const date = new Date('2025-10-14T00:00:00Z');
+import { describe, expect, it } from "vitest";
+import { formatDate } from "../../../src/helpers/formatDate";
+describe("formatDate helper", () => {
+    it("should format a valid date correctly", () => {
+        const date = new Date("2025-10-14T00:00:00Z");
         const formatted = formatDate(date);
-        expect(formatted).toBe('14 Oct 2025');
+        expect(formatted).toBe("14 Oct 2025");
     });
-    it('should format date in custom locale', () => {
-        const date = new Date('2025-10-14T00:00:00Z');
-        const formatted = formatDate(date, 'en-US');
+    it("should format date in custom locale", () => {
+        const date = new Date("2025-10-14T00:00:00Z");
+        const formatted = formatDate(date, "en-US");
         expect(formatted).toMatch(/Oct/);
     });
-    it('should throw an error for invalid date', () => {
+    it("should throw an error for invalid date", () => {
         // @ts-expect-error testing invalid date
-        expect(() => formatDate('not-a-date')).toThrowError('Invalid Date');
+        expect(() => formatDate("not-a-date")).toThrowError("Invalid Date");
     });
 });

package/dist/tests/unit/index.test.js

@@ -1,7 +1,7 @@
-import { describe, it, expect } from 'vitest';
-import * as utils from '../../src';
-describe('index.ts', () => {
-    it('should export all modules correctly', () => {
+import { describe, expect, it } from "vitest";
+import * as utils from "../../src";
+describe("index.ts", () => {
+    it("should export all modules correctly", () => {
         expect(utils).toBeDefined();
         expect(utils.formatDate).toBeInstanceOf(Function); // Example for a helper
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@togatherlabs/shared-utils",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Shared utility functions, constants, and types for ToGather microservices",
   "type": "module",
   "main": "dist/index.js",
@@ -55,7 +55,11 @@
     "test:ui": "vitest --ui",
     "commit": "git-cz",
     "package:patch": "pnpm version patch",
+    "package:minor": "pnpm version minor",
+    "package:major": "pnpm version major",
     "package:publish": "pnpm publish --access public",
-    "release": "pnpm build && git add . && pnpm commit && pnpm package:patch && git push --follow-tags && pnpm package:publish"
+    "release:patch": "pnpm build && git add . && pnpm commit && pnpm package:patch && git push --follow-tags && pnpm package:publish",
+    "release:minor": "pnpm build && git add . && pnpm commit && pnpm package:minor && git push --follow-tags && pnpm package:publish",
+    "release:major": "pnpm build && git add . && pnpm commit && pnpm package:major && git push --follow-tags && pnpm package:publish"
   }
 }