@togatherlabs/shared-utils 1.0.0 → 1.0.1

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@togatherlabs/shared-utils",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "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"
   }
 }