JSPM

ResLib is a lightweight, production-ready TypeScript library for decorator-based resource management and application utilities. ResLib provides a modular framework for building scalable applications with features like authentication, internationalization, validation, session management, and observable patterns. It is fully cross-platform—compatible with web, Node.js, React Native (including Expo), and server environments like NestJS—while delivering strong type safety, high flexibility, and optimized performance without relying on platform-specific dependencies.

Table of Contents

• Key Features
• Supported Platforms
• Getting Started
• Usage
• Advanced Examples
• Contributing
• License

🚀 Key Features

• Decorator-Driven Resource Management: Use decorators to intuitively define and manage resources, resulting in cleaner, more expressive code.
• Modular Architecture: Treat every component as a resource, promoting reusability and better organization of application logic.
• Extensible Framework: Effortlessly extend core functionalities by adding custom field types, decorators, and plugins tailored to specific project needs.
• Customizable FieldMeta Types: Support for various built-in field types (such as number, dropdown, selectResource) that can be customized with specific properties for flexible data handling.
• Type Safety: Developed with TypeScript, ensuring robust type-checking for a reliable foundation for scalable applications.
• Intuitive API: Enjoy a developer-friendly API that leverages TypeScript features for smooth auto-completion and type hints.
• Dynamic Ecosystem: Easily adapt to evolving project requirements by integrating external decorators and features, allowing for a responsive and flexible development environment.
• Production Ready: Optimized for performance, with comprehensive testing, documentation, and support for major platforms.

🌐 Supported Platforms

• Web: Full browser support with modern bundlers
• React Native: Seamless integration with Expo and bare React Native
• NestJS: Server-side framework support for backend applications
• Node.js: Server-side JavaScript runtime compatibility

⚙️ Getting Started

To begin using ResLib, follow these steps:

1. Prerequisites

Make sure you have the following installed on your machine:

• Node.js (version 16 or higher)
• npm (Node Package Manager)

2. 🛠️ Install Required Packages

To set up ResLib, run the following command:

npm install reslib reflect-metadata
# or
yarn add reslib reflect-metadata

For Expo/React Native projects:

npx expo install reslib reflect-metadata

For NestJS projects:

npm install reslib reflect-metadata @nestjs/common

Also, install the necessary TypeScript dev dependencies:

npm install --save-dev typescript @types/node # or yarn add -D typescript @types/node

3. TypeScript Configuration

Create a tsconfig.json file in your project root with the following configuration:

Create a tsconfig.json file in your project root with the following configuration:

{
    "compilerOptions": {
      "esModuleInterop": true,
      "forceConsistentCasingInFileNames": true,
      "target": "es6",                          // Use ES6 or higher
      "module": "commonjs",                     // Use commonjs module system
      "experimentalDecorators": true,           // Enable experimental support for decorators
      "emitDecoratorMetadata": true,             // Enable emitting design:type metadata
      "strict": true,                            // Enable all strict type checking options
      "skipLibCheck": true                       // Skip type checking of declaration files
    },
    "include": ["src/**/*"],
    "exclude": ["node_modules"]
}

4. Import reflect-metadata

In your entry file (usually index.ts or app.ts), ensure that you import reflect-metadata at the very top of the file. This is required to enable metadata reflection for decorators.

import 'reflect-metadata';

📚 Documentation

Resources

• Resources are the foundation of ResLib. Use the @ResourceMeta decorator to define any logical entity (models, components, etc.).

• Fields: Add fields to your resources using the @FieldMeta decorator, specifying field types and options.

• symbol : Simple symbol field;

• switch : Can be a number of a boolean;

• checkbox: Can be a number of a boolean;

Validation

Powerful validation system with 70+ rules, decorators, functional schemas, and batch processing.

• Decorator-based: @IsRequired(), @IsEmail(), etc.
• Object-based (Zod-like): Validator.object({ email: ['Required', 'Email'] }).
• Batch validation: Validator.validateBulk(User, data).
• Async & i18n support.

Once you have installed the necessary packages and set up TypeScript, you can start defining resources and fields using ResLib decorators.

Basic Example

import 'reflect-metadata';
import { ResourceMeta, FieldMeta } from 'reslib';

@ResourceMeta()
class User {
  @FieldMeta({ type: 'string' })
  name: string;

  @FieldMeta({ type: 'number' })
  age: number;

  @FieldMeta({ type: 'email' })
  email: string;
}

Examples

Defining Custom FieldMeta Types

@FieldMeta({ type: 'dropdown', options: ['Admin', 'User', 'Guest'] })
role: string;

@FieldMeta({ type: 'selectResource', resourceName: 'Product' })
favoriteProduct: string;

Creating Extensible Decorators

You can easily create and register new decorators to extend the functionality of your resources.

function CustomField(options: { customProp: string }) {
  return function (target: any, propertyKey: string) {
    // Custom decorator logic
    Reflect.defineMetadata(
      'customProp',
      options.customProp,
      target,
      propertyKey
    );
  };
}

Advanced Examples

🔄 Extending the Framework

ResLib is designed for flexibility. You can add your own custom field types or extend existing ones with full TypeScript support.

Extending FieldMeta Types

You can easily extend the field types available in ResLib by creating custom decorators. To extend field types and register custom options (e.g., a rating field), use TypeScript's declaration merging.

function ExtendedField(type: string, options: any) {
    return function (target: any, propertyKey: string) {
        Reflect.defineMetadata('design:type', type, target, propertyKey);
        Reflect.defineMetadata('field:options', options, target, propertyKey);
    };
}

// Define a new field type for a color picker
@ExtendedField('colorPicker', { defaultColor: '#000000' })
color: string;

This allows ResLib to recognize new custom field types, complete with IntelliSense support.

Adding New Resources

You can create new resources and leverage the existing decorators for rich resource definitions.

@ResourceMeta()
class Product {
  @FieldMeta({ type: 'string' })
  productName: string;

  @FieldMeta({ type: 'number' })
  price: number;

  @FieldMeta({
    type: 'string',
    options: { enum: ['In Stock', 'Out of Stock'] },
  })
  availability: string;
}

Custom Decorator for Advanced Logic

You can also create custom decorators that implement advanced logic, such as validation or transformation.

function IsPositive(target: any, propertyKey: string) {
    const value = target[propertyKey];
    if (value < 0) {
        throw new Error(`${propertyKey} must be a positive number.`);
    }
}

@ResourceMeta()
class Order {
    @FieldMeta({ type: 'number' })
    @IsPositive
    totalAmount: number;

    @FieldMeta({ type: 'string' })
    customerName: string;
}

Using Extended FieldMeta Types

Here’s how you can use the newly defined field types in a resource:

@ResourceMeta()
class EnhancedUser {
  @FieldMeta({ type: 'string' })
  name: string;

  @ExtendedField('colorPicker', { defaultColor: '#FF0000' })
  favoriteColor: string;
}

🔌 Plugins & Extensions

ResLib can be extended with plugins and custom modules. Define new decorators, extend resource behavior, and add complex validation logic as needed.

Example: Custom Decorator Plugin

import { ResourceMeta, FieldMeta, customDecorator } from 'reslib';

function LogField() {
  return customDecorator((target, key) => {
    console.log(`FieldMeta '${key}' has been initialized.`);
  });
}

@ResourceMeta
class Product {
  @LogField()
  @FieldMeta({ type: "number" })
  price: number;
}

🧩 Contributing

We welcome contributions! Please see our Contributing Guide for details on how to get started.

📜 License

ResLib is licensed under the MIT License.

🛠 Built With

• TypeScript: Type-safe, scalable development.
• Reflect-metadata: For decorator metadata reflection.
• Custom Decorators: A clean and declarative way to extend functionality.

👏 Acknowledgements

Thanks to the open-source community for contributions and inspiration.

📬 Contact

For support or inquiries:

• GitHub:  GitHub Link