@uisap/create

A scaffolding tool for quickly setting up a new project using @uisap/core, a lightweight, modular, and Laravel-inspired framework built on top of Fastify. With @uisap/create, you can bootstrap a fully functional project in seconds, complete with configuration files, models, controllers, routes, events, listeners, jobs, and more.

Installation

You don’t need to install @uisap/create globally. Use npx to run it directly:

npx @uisap/create my-app

This command creates a new project directory named my-app with all necessary files and dependencies.

Prerequisites

• Node.js: Version 16.x or higher.
• Redis: Required for queue processing and broadcasting (default: localhost:6379).
• Database: Supports MySQL, PostgreSQL, SQLite, MariaDB, MSSQL, or Oracle. Configure in config/database.js.

Ensure Redis and your chosen database are running before starting the application.

Directory Structure

The scaffolded project follows a structured layout inspired by Laravel, designed for modularity and scalability:

my-app/
├── app/
│   ├── console/
│   │   └── commands/
│   │       └── ExampleCommand.js  (optional, created with make:command)
│   ├── controllers/
│   │   └── ExampleController.js
│   ├── events/
│   │   ├── ExampleEvent.js
│   │   └── OrderShipped.js
│   ├── jobs/
│   │   └── ExampleJob.js
│   ├── listeners/
│   │   ├── ExampleListener.js
│   │   └── SendShipmentNotification.js
│   ├── models/
│   │   └── ExampleModel.js
│   └── providers/
│       └── AppServiceProvider.js
├── config/
│   ├── app.js
│   ├── broadcast.js
│   ├── cors.js
│   ├── database.js
│   ├── events.js
│   ├── queue.js
│   └── schedule.js
├── routes/
│   ├── api.js
│   ├── channels.js
│   └── console.js
├── .env.example
├── index.js
├── package.json
├── uisap.js
└── README.md

Starting the Application

1. Navigate to your project directory:

cd my-app

2. Copy the environment file and configure it (e.g., database credentials):

cp .env.example .env

3. Install dependencies and start the application:

npm install
npm run dev

The npm run dev command starts both the main server (default: http://localhost:4115) and the queue worker. To run the worker separately (e.g., for debugging):

npm run worker

Features

• Routing: Define API routes in routes/api.js using @uisap/core's routing system, with support for middleware.
• Controllers: Extend BaseController for handling HTTP requests, with dependency injection for models and services.
• Models: Use Model for database interactions with Sequelize, supporting multiple dialects (MySQL, PostgreSQL, SQLite, etc.).
• Dependency Injection: Automatic injection of models, services, and other dependencies via the container.
• Events & Broadcasting: Real-time updates with Socket.IO, Redis, Pusher, or Ably, using custom events and listeners.
• Queue Processing: Asynchronous job handling with Bull, configurable via Redis.
• Scheduling: Cron-like task scheduling with toad-scheduler, supporting flexible intervals (e.g., daily, hourly).
• CLI Tool: The uisap.js CLI provides commands for generating components and managing tasks.

CLI Commands

The uisap.js CLI (invoked via node uisap or npx uisap) offers commands to generate components and manage the application. Run from the project root:

Create a Controller

node uisap make:controller Example

Generates app/controllers/ExampleController.js.

Create a Model

node uisap make:model Example

Generates app/models/Example.js.

Create a Middleware

node uisap make:middleware Auth

Generates app/middlewares/Auth.js.

Create a Job

node uisap make:job ProcessData

Generates app/jobs/ProcessData.js.

Create an Event

node uisap make:event OrderShipped

Generates app/events/OrderShipped.js.

With a listener binding:

node uisap make:event OrderShipped --listener SendShipmentNotification

Updates app/providers/AppServiceProvider.js to bind the listener.

Create a Listener

node uisap make:listener SendShipmentNotification

Generates app/listeners/SendShipmentNotification.js.

With an event binding:

node uisap make:listener SendShipmentNotification --event OrderShipped

Updates app/providers/AppServiceProvider.js.

With queue support:

node uisap make:listener SendShipmentNotification --queue

Adds the listener to config/queue.js as a handler.

Create a Command

node uisap make:command CleanLogs

Generates app/console/commands/CleanLogs.js.

With scheduling:

node uisap make:command CleanLogs --schedule

Adds the command to config/schedule.js.

Run Scheduled Tasks

node uisap schedule:run

Executes all scheduled tasks once.

List Scheduled Tasks

node uisap schedule:list

Displays a table of scheduled tasks.

Process Queue Jobs

node uisap queue:work [--queue <queue>] [--tries <tries>]

Processes jobs from the specified queue (default: default).

Test Broadcasting

node uisap broadcast:test [--channel <channel>] [--event <event>] [--data <data>]

Sends a test broadcast message to the specified channel.

Start the Application

node uisap serve [--port <port>]

Runs npm run dev with an optional port (default: 4115).

Display Help

node uisap help

Shows detailed help for all commands.

Event and Listener Integration

Events and listeners are tightly integrated for real-time and asynchronous processing. Use the --listener or --event options to bind them automatically in AppServiceProvider.js.

Example:

node uisap make:event OrderShipped --listener SendShipmentNotification

This command generates app/events/OrderShipped.js and updates app/providers/AppServiceProvider.js:

import { ServiceProvider, EventFacade as Event } from '@uisap/core';
import SendShipmentNotification from '../listeners/SendShipmentNotification.js';

export class AppServiceProvider extends ServiceProvider {
  register() {
   // Register custom services or bindings
  }

  async boot() {
   // Bind event to listener
   Event.listen('OrderShipped', new SendShipmentNotification(), 10);
  }
}

When the OrderShipped event is fired, the SendShipmentNotification listener is triggered, either directly or via a queue if configured.

Configuration

Key configuration files are located in the config/ directory:

• app.js: General application settings (port, logging level, etc.).
• database.js: Database connection settings for Sequelize and Redis.
• broadcast.js: Broadcasting driver configuration (Redis, Pusher, or Ably).
• queue.js: Queue settings and job handlers.
• schedule.js: Scheduled task definitions.
• cors.js: CORS settings for API endpoints.
• events.js: Event listener mappings.

Modify .env to override defaults (e.g., DB_CONNECTION, REDIS_HOST, JWT_SECRET).

Example Usage

Creating a Record and Firing an Event

In app/controllers/ExampleController.js:

async index(request, reply) {
  const { id, data } = request.body;
  const record = await this.exampleModel.createRecord({ id, data });
  await Event.fire(new ExampleEvent({ recordId: record.id, data }));
  return reply.send({ message: 'Record created', record });
}

Handling an Event

In app/listeners/ExampleListener.js:

async handle(event, app) {
  app.fastify.logger.info('ExampleListener handling event', {
   recordId: event.data.recordId,
   data: event.data.data,
  });
  // Perform async operations, e.g., store in Redis
  await app.container.make('keyValueStore').set(
   `listener:${event.data.recordId}:handled`,
   JSON.stringify(event.data),
   3600
  );
}

Scheduling a Task

In routes/console.js:

import { ScheduleFacade } from '@uisap/core';

export default async function consoleRoutes(app) {
  ScheduleFacade.call(async (app) => {
   app.fastify.logger.info('Sample scheduled task executed');
  }).daily('0:00');
  ScheduleFacade.setTimezone('Europe/Istanbul').run();
}

Extending the Framework

• Custom Providers: Create new providers in app/providers/ to register services or bind event listeners.
• Middleware: Add custom middleware in app/middlewares/ for request processing.
• Plugins: Register Fastify plugins via app.plugin() in index.js.
• Commands: Extend the CLI by adding commands in app/console/commands/.

Troubleshooting

• Redis Connection Issues: Ensure Redis is running and the .env file has correct REDIS_HOST and REDIS_PORT.
• Database Errors: Verify database credentials in .env and check config/database.js.
• Queue Processing: Run npm run worker separately if jobs aren't processing.
• Logs: Check the logs/ directory for detailed error messages.

Contributing

Contributions are welcome! Please submit issues or pull requests to the @uisap/create repository. Ensure you include tests and follow the coding style.

License

@uisap/create and @uisap/core are licensed under the MIT License.