@doyzfin/common

@doyzfin/common

Shared Foundation for the ForgeKit Ecosystem

Reusable utilities, types, helpers, constants, and core abstractions designed for enterprise-grade TypeScript applications.

TypeScript First • Tree Shakable • Fully Typed • Zero Runtime Dependencies

Overview

@doyzfin/common is the foundation package of the ForgeKit ecosystem.

It contains reusable building blocks shared across every ForgeKit package, helping maintain consistency, reduce duplication, and provide a predictable developer experience.

This package is framework agnostic and can be used independently in any TypeScript project.

Why Use @doyzfin/common?

Instead of rewriting the same utilities for every project, ForgeKit provides a centralized package containing production-ready utilities and abstractions.

Benefits include:

• Shared types
• Consistent error handling
• Utility helpers
• Result pattern
• Event system
• Tree manipulation
• Object utilities
• Constants

Features

• ✅ Result Pattern
• ✅ Custom Errors
• ✅ Event Bus
• ✅ Utility Functions
• ✅ Shared Constants
• ✅ Object Helpers
• ✅ Tree Helpers
• ✅ Shared Types
• ✅ Zero Runtime Dependencies
• ✅ Fully Typed

Installation

pnpm add @doyzfin/common

Requirements

• Node.js 20+
• TypeScript 5.9+

Quick Start

import { ok, err } from "@doyzfin/common";

const result = ok({
  id: 1,
  name: "John",
});

if (result.success) {
  console.log(result.data);
}

Package Structure

src/

constants/
errors/
events/
helpers/
types/
utils/

index.ts

Included Modules

Result Pattern

Provides a clean way to return success or failure without throwing exceptions.

const result = ok(data);

const error = err("User not found");

Error Handling

Create consistent application errors using custom error classes.

import { ForgeError, ValidationError, NotFoundError } from "@doyzfin/common";

// Throwing structured error classes
throw new ValidationError("Invalid email format", { email: "format" });

Event Bus

Lightweight, type-safe publish-subscribe implementation.

import { EventBus } from "@doyzfin/common";

const bus = new EventBus();

// Subscribe to event
const unsubscribe = bus.on("user.created", (user) => {
  console.log(`User created: ${user.name}`);
});

// Emit event
bus.emit("user.created", { name: "Alice" });

// Clean up listener
unsubscribe();

Object & Array Utilities

Helper utilities for manipulating arrays and objects.

import { deepMerge, objectDiff, chunk, memoize, uuid, debounce, throttle, retry } from "@doyzfin/common";

// Deep Merge
const merged = deepMerge({ a: { b: 1 } }, { a: { c: 2 } });

// Object Diff
const diff = objectDiff({ a: 1, b: 2 }, { b: 2, c: 3 });
// { added: { c: 3 }, deleted: { a: 1 }, updated: {} }

// Array Chunking
const chunks = chunk([1, 2, 3, 4], 2); // [[1, 2], [3, 4]]

// UUID Generation
const id = uuid(); // random v4 UUID

Shared Types

Reusable type definitions used across the ForgeKit ecosystem.

import type { ApiResponse, DeepPartial, Dictionary, Nullable, Optional, PaginatedResult } from "@doyzfin/common";

const successResponse: ApiResponse<string> = {
  success: true,
  data: "Operation complete",
};

Design Principles

This package follows several important principles:

• Composition over inheritance
• Strong typing
• Functional utilities
• Small focused modules
• Tree-shakable exports
• Zero unnecessary dependencies

Performance

• Optimized for tree shaking
• Minimal runtime overhead
• Designed for enterprise applications
• Zero unnecessary allocations

Testing

Run tests

pnpm test

Run coverage

pnpm test:coverage

Documentation

Additional documentation is available inside the /docs directory.

Topics include:

• Utilities
• Error Handling
• Event System
• Best Practices

Roadmap

Current

• Result Pattern
• Event Bus
• Utilities

Upcoming

• Logger
• Retry Helpers
• Async Helpers
• Collection Utilities

Contributing

Please read:

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md

before opening pull requests.

License

Commercial License

This package is part of the ForgeKit ecosystem.

Redistribution or resale of the original source code is prohibited.

Support

Need help?

• Documentation
• GitHub Discussions
• GitHub Issues
• Premium Support

Built with ❤️ for enterprise developers.

Part of the ForgeKit ecosystem.