Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/boris-fouomene/reslib

Lightweight TypeScript library providing decorator-based resource management and utilities. Offers auth, i18n, validation, sessions, observables, and cross-platform support (web, Node.js, React Native, NestJS) with strong typing and modular design.
https://github.com/boris-fouomene/reslib

api authentication dynamic expo extensible i18n javascript nestjs nextjs nodejs object-oriented-programming react-native reactjs resources safety types typescript validation web

Last synced: 3 months ago
JSON representation

Lightweight TypeScript library providing decorator-based resource management and utilities. Offers auth, i18n, validation, sessions, observables, and cross-platform support (web, Node.js, React Native, NestJS) with strong typing and modular design.

Awesome Lists containing this project

README 

          
**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](#key-features)

- [Supported Platforms](#supported-platforms)

- [Getting Started](#getting-started)

- [Usage](#usage)

- [Advanced Examples](#advanced-examples)

- [Contributing](#contributing)

- [License](#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:



```typescript

npm install reslib reflect-metadata

# or

yarn add reslib reflect-metadata

```



For Expo/React Native projects:



```typescript

npx expo install reslib reflect-metadata

```



For NestJS projects:



```typescript

npm install reslib reflect-metadata @nestjs/common

```



Also, install the necessary TypeScript dev dependencies:



```plaintext

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:



```typescript

{

    "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.



```typescript

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**



```typescript

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**



```typescript

@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.



```typescript

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**.



```typescript

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.



```typescript

@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.



```typescript

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:



```typescript

@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



```typescript

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](CONTRIBUTING.md) 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](https://github.com/boris-fouomene/reslib)