@stone-js/starters 0.8.3

package/full-service-declarative/app/Application.ts

@@ -0,0 +1,327 @@
+import {
+  IncomingHttpEvent,
+  OutgoingHttpResponse,
+  IncomingHttpEventOptions
+} from '@stone-js/http-core'
+import {
+  NodeHttp,
+  MetaBodyEventMiddleware,
+  MetaFilesEventMiddleware
+} from '@stone-js/node-http-adapter'
+import {
+  Hook,
+  isEmpty,
+  StoneApp,
+  LogLevel,
+  IContainer,
+  IBlueprint,
+  AdapterContext,
+  BlueprintContext,
+  AdapterEventBuilderType,
+  AdapterHookListenerContext
+} from '@stone-js/core'
+import { getString } from '@stone-js/env'
+import { Routing } from '@stone-js/router'
+import { NodeConsole } from '@stone-js/node-cli-adapter'
+import { PipelineHookContext } from '@stone-js/pipeline'
+
+/**
+ * Application
+ *
+ * This is the main application entry point.
+ *
+ * @StoneApp() is used to enable the Stone application, it is mandatory.
+ * @Routing() is used to enable the routing feature.
+ * @NodeHttp() is used to enable the Node HTTP adapter.
+ * @NodeConsole() is used to enable the Node Console adapter.
+ * @NodeConsole() requires the incoming event type.
+ * BodyEventMiddleware is used to parse the incoming event body.
+ * BodyEventMiddleware is imported because it is not installed by default.
+ *
+ * Note: In this example we implement the IBlueprintHook, IAdapterHook and IKernelHook interfaces for demonstration purposes.
+ */
+@Routing()
+@NodeConsole()
+@StoneApp({ name: 'MyApps', logger: { level: LogLevel.INFO } })
+@NodeHttp({ default: true, middleware: [MetaBodyEventMiddleware, MetaFilesEventMiddleware], url: getString('BASE_URL', 'http://localhost:8080') })
+export class Application {
+  /**
+   * Run before the blueprint is prepared
+   *
+   * @param context - The blueprint context
+   */
+  @Hook('onPreparingBlueprint')
+  onPreparingBlueprint ({ blueprint, modules }: BlueprintContext): void {
+    blueprint.set('tmpBlueprintTimer', Date.now())
+    console.log(`Preparing blueprint by introspecting ${modules.length} modules...`)
+  }
+
+  /**
+   * Run before each blueprint middleware is processed
+   *
+   * @param context - The pipeline context
+   */
+  @Hook('onProcessingBlueprintMiddleware')
+  onProcessingBlueprintMiddleware ({ passable, pipe }: PipelineHookContext<BlueprintContext, IBlueprint>): void {
+    passable.blueprint.set(`tmpBlueprintMiddleware.${String(pipe.module.name)}`, Date.now())
+  }
+
+  /**
+   * Run after each blueprint middleware is processed
+   *
+   * @param context - The pipeline context
+   */
+  @Hook('onBlueprintMiddlewareProcessed')
+  onBlueprintMiddlewareProcessed ({ passable, pipe }: PipelineHookContext<BlueprintContext, IBlueprint>): void {
+    const name = `tmpBlueprintMiddleware.${String(pipe.module.name)}`
+    const start = passable.blueprint.get(name, 0)
+    const Type = pipe.isClass !== undefined ? 'Class' : pipe.isFactory !== undefined ? 'Factory' : pipe.isAlias !== undefined ? 'Alias' : 'Callable'
+    const value = {
+      Middleware: pipe.module.name,
+      Type,
+      Priority: pipe.priority,
+      'Execution Time': `${Date.now() - start}ms`
+    }
+
+    passable.blueprint.set(name, value)
+  }
+
+  /**
+   * Run after the blueprint is prepared
+   *
+   * @param context - The blueprint context
+   */
+  @Hook('onBlueprintPrepared')
+  onBlueprintPrepared ({ blueprint }: BlueprintContext): void {
+    const timer = Date.now() - blueprint.get('tmpBlueprintTimer', 0)
+    const middleware = Object.values(blueprint.get('tmpBlueprintMiddleware', {}))
+    const message = `Blueprint prepared in ${timer}ms, with ${middleware.length} middleware`
+
+    console.table(middleware)
+    console.log(message)
+  }
+
+  /**
+   * Run before the application starts
+   *
+   * @param context - The adapter context
+   */
+  @Hook('onStart')
+  onStart ({ blueprint, context }: AdapterHookListenerContext): void {
+    console.log('Starting application...')
+    console.log('Context isEmpty?', isEmpty(context))
+    console.log('Blueprint keys:', Object.keys(blueprint.all()).length)
+  }
+
+  /**
+   * Run before each adapter middleware is processed
+   *
+   * @param context - The pipeline context
+   */
+  @Hook('onProcessingAdapterMiddleware')
+  onProcessingAdapterMiddleware ({ passable, pipe, pipes }: PipelineHookContext<
+  AdapterContext<unknown, unknown, unknown, IncomingHttpEvent, IncomingHttpEventOptions, OutgoingHttpResponse>,
+  AdapterEventBuilderType<any>
+  >): void {
+    console.log('Processing adapter middleware...')
+    console.log('Middleware count:', pipes.length)
+    console.log('Middleware name:', pipe.name)
+    console.log('IncomingEvent isEmpty?', isEmpty(passable.incomingEvent))
+  }
+
+  /**
+   * Run after each adapter middleware is processed
+   *
+   * @param context - The pipeline context
+   */
+  @Hook('onAdapterMiddlewareProcessed')
+  onAdapterMiddlewareProcessed ({ passable, pipe, pipes }: PipelineHookContext<
+  AdapterContext<unknown, unknown, unknown, IncomingHttpEvent, IncomingHttpEventOptions, OutgoingHttpResponse>,
+  AdapterEventBuilderType<any>
+  >): void {
+    console.log('Adapter middleware processed...')
+    console.log('Middleware count:', pipes.length)
+    console.log('Middleware name:', pipe.name)
+    console.log('IncomingEvent isEmpty?', isEmpty(passable.incomingEvent))
+  }
+
+  /**
+   * Run before building each incoming event
+   *
+   * @param context - The adapter context
+   */
+  @Hook('onBuildingIncomingEvent')
+  onBuildingIncomingEvent ({ context }: AdapterHookListenerContext<
+  AdapterContext<unknown, unknown, unknown, IncomingHttpEvent, IncomingHttpEventOptions, OutgoingHttpResponse>
+  >): void {
+    console.log('Building incoming event...')
+    console.log('IncomingEvent isEmpty?', isEmpty(context?.incomingEvent))
+  }
+
+  /**
+   * Run before handling each adapter error
+   *
+   * @param context - The adapter context
+   */
+  @Hook('onHandlingAdapterError')
+  onHandlingAdapterError ({ error }: AdapterHookListenerContext<
+  AdapterContext<unknown, unknown, unknown, IncomingHttpEvent, IncomingHttpEventOptions, OutgoingHttpResponse>
+  >): void {
+    console.error('Handling adapter error...')
+    console.error('Error:', error)
+  }
+
+  /**
+   * Run before building each outgoing response
+   *
+   * @param context - The adapter context
+   */
+  @Hook('onBuildingRawResponse')
+  onBuildingRawResponse ({ context }: AdapterHookListenerContext<
+  AdapterContext<unknown, unknown, unknown, IncomingHttpEvent, IncomingHttpEventOptions, OutgoingHttpResponse>
+  >): void {
+    console.log('Building raw response...')
+    console.log('IncomingEvent isEmpty?', isEmpty(context?.incomingEvent))
+    console.log('OutgoingResponse isEmpty?', isEmpty(context?.outgoingResponse))
+  }
+
+  /**
+   * Run just before the application stops
+   *
+   * @param context - The adapter context
+   */
+  @Hook('onStop')
+  onStop ({ blueprint, context }: AdapterHookListenerContext): void {
+    console.log('Stopping application...')
+    console.log('Context isEmpty?', isEmpty(context))
+    console.log('Blueprint keys:', Object.keys(blueprint.all()).length)
+  }
+
+  /**
+   * Run after the application is initialized
+   * The container is available at this point.
+   * All services are registered and ready to be used.
+   *
+   * @param container - The container
+   */
+  @Hook('onInit')
+  onInit (container: IContainer): void {
+    console.log('Initializing application...')
+    console.log('Container services count:', container.getBindings().size)
+  }
+
+  /**
+   * Run before handling each event
+   *
+   * @param container - The container
+   */
+  @Hook('onHandlingEvent')
+  onHandlingEvent (container: IContainer): void {
+    try {
+      console.log('Handling event...')
+      container.make('event')
+    } catch (error: any) {
+      console.log('The incoming event is not yet bound at this stage', error.message)
+    }
+  }
+
+  /**
+   * Run before processing each kernel middleware
+   *
+   * @param context - The pipeline context
+   */
+  @Hook('onProcessingKernelMiddleware')
+  onProcessingKernelMiddleware (
+    { passable, pipe, pipes }: PipelineHookContext<IncomingHttpEvent, OutgoingHttpResponse>
+  ): void {
+    console.log('Processing kernel middleware...')
+    console.log('Middleware count:', pipes.length)
+    console.log('Middleware name:', pipe.name)
+    console.log('Incoming Source name', passable.source.platform)
+  }
+
+  /**
+   * Run after processing each kernel middleware
+   *
+   * @param context - The pipeline context
+   */
+  @Hook('onKernelMiddlewareProcessed')
+  onKernelMiddlewareProcessed (
+    { passable, pipe, pipes }: PipelineHookContext<IncomingHttpEvent, OutgoingHttpResponse>
+  ): void {
+    console.log('Kernel middleware processed...')
+    console.log('Middleware count:', pipes.length)
+    console.log('Middleware name:', pipe.name)
+    console.log('Incoming Source name', passable.source.platform)
+  }
+
+  /**
+   * Run before executing each event handler
+   *
+   * @param container - The container
+   */
+  @Hook('onExecutingEventHandler')
+  onExecutingEventHandler ({ event }: { event: IncomingHttpEvent }): void {
+    console.log('Executing event handler...')
+    console.log('The incoming event is yet bound at this stage', event.source.platform)
+  }
+
+  /**
+   * Run before handling each error
+   *
+   * @param container - The container
+   */
+  @Hook('onExecutingErrorHandler')
+  onExecutingErrorHandler ({ error }: { error: any }): void {
+    console.log('Executing error handler...')
+    console.log('Error', error)
+  }
+
+  /**
+   * Run before preparing each response
+   *
+   * @param container - The container
+   */
+  @Hook('onPreparingResponse')
+  onPreparingResponse ({ response }: { response: OutgoingHttpResponse }): void {
+    console.log('Preparing response...')
+    console.log('Response headers', response.headers)
+  }
+
+  /**
+   * Run after preparing each response
+   *
+   * @param container - The container
+   */
+  @Hook('onResponsePrepared')
+  onResponsePrepared ({ response }: { response: OutgoingHttpResponse }): void {
+    console.log('Response prepared...')
+    console.log('Response headers', response.headers)
+  }
+
+  /**
+   * Run after handling each event
+   *
+   * @param context - The pipeline context
+   */
+  @Hook('onEventHandled')
+  onEventHandled (
+    { event, response }: { event: IncomingHttpEvent, response: OutgoingHttpResponse }
+  ): void {
+    console.log('Event handled...')
+    console.log('Event headers', event.headers)
+    console.log('Response headers', response.headers)
+  }
+
+  /**
+   * Run after executing each event handler
+   *
+   * @param container - The container
+   */
+  @Hook('onTerminate')
+  onTerminate (container: IContainer): void {
+    console.log('Terminating event handling...')
+    console.log('Is IncomingEvent exist', container.bound('event'))
+    console.log('Is OutgoingResponse exist', container.bound('response'))
+  }
+}

package/full-service-declarative/app/commands/ListSessionsCommand.ts

@@ -0,0 +1,70 @@
+import { UserService } from '../services/UserService'
+import { SessionService } from '../services/SessionService'
+import { ILogger, IncomingEvent, isEmpty } from '@stone-js/core'
+import { Command, CommandBuilder, ICommandHandler } from '@stone-js/node-cli-adapter'
+
+/**
+ * ListSessionsCommandOptions
+*/
+export interface ListSessionsCommandOptions {
+  logger: ILogger
+  userService: UserService
+  sessionService: SessionService
+}
+
+/**
+ * List sessions command
+ */
+@Command({
+  alias: 'ls',
+  name: 'list-sessions',
+  desc: 'List sessions',
+  options: (yargs: CommandBuilder) => {
+    return yargs
+      .option('email', {
+        alias: 'e',
+        type: 'string',
+        default: undefined,
+        desc: 'Filter sessions by email'
+      })
+      .option('limit', {
+        alias: 'l',
+        type: 'number',
+        default: false,
+        desc: 'Number of sessions to list'
+      })
+  }
+})
+export class ListSessionsCommand implements ICommandHandler<IncomingEvent> {
+  private readonly logger: ILogger
+  private readonly userService: UserService
+  private readonly sessionService: SessionService
+
+  /**
+   * Create a new instance of ListSessionsCommand
+   *
+   * @param logger
+   * @param sessionService
+   */
+  constructor ({ logger, sessionService, userService }: ListSessionsCommandOptions) {
+    this.logger = logger
+    this.userService = userService
+    this.sessionService = sessionService
+  }
+
+  /**
+   * Handler for the ListSessionsCommand
+   *
+   * @param event - Incoming event
+   */
+  async handle (event: IncomingEvent): Promise<void> {
+    const email = event.get<number>('email')
+    const limit = event.get<number>('limit', 10)
+    const user = isEmpty(email) ? undefined : await this.userService.findByEmail({ email })
+    const sessions = isEmpty(user)
+      ? await this.sessionService.list(limit)
+      : await this.sessionService.getByUser(user, limit)
+    this.logger.info('List sessions command')
+    console.table(sessions)
+  }
+}

package/full-service-declarative/app/commands/ListUsersCommand.ts

@@ -0,0 +1,56 @@
+import { UserService } from '../services/UserService'
+import { ILogger, IncomingEvent } from '@stone-js/core'
+import { Command, CommandBuilder, ICommandHandler } from '@stone-js/node-cli-adapter'
+
+/**
+ * ListUsersCommandOptions
+*/
+export interface ListUsersCommandOptions {
+  logger: ILogger
+  userService: UserService
+}
+
+/**
+ * List users command
+ */
+@Command({
+  alias: 'lu',
+  name: 'list-users',
+  desc: 'List users',
+  options: (yargs: CommandBuilder) => {
+    return yargs
+      .option('limit', {
+        alias: 'l',
+        type: 'number',
+        default: false,
+        desc: 'Number of users to list'
+      })
+  }
+})
+export class ListUsersCommand implements ICommandHandler<IncomingEvent> {
+  private readonly logger: ILogger
+  private readonly userService: UserService
+
+  /**
+   * Create a new instance of ListUsersCommand
+   *
+   * @param logger
+   * @param userService
+   */
+  constructor ({ logger, userService }: ListUsersCommandOptions) {
+    this.logger = logger
+    this.userService = userService
+  }
+
+  /**
+   * Handler for the ListUsersCommand
+   *
+   * @param event - Incoming event
+   */
+  async handle (event: IncomingEvent): Promise<void> {
+    const limit = event.get<number>('limit', 10)
+    const users = await this.userService.list(limit)
+    this.logger.info('List users command')
+    console.table(users)
+  }
+}

package/full-service-declarative/app/configurations/AppConfiguration.ts

@@ -0,0 +1,52 @@
+import { Config } from '@libsql/client'
+import { getString } from '@stone-js/env'
+import { CORSHeadersMiddleware } from '@stone-js/http-core'
+import { Configuration, defineBlueprintMiddleware, IBlueprint, IConfiguration, LogLevel, Promiseable } from '@stone-js/core'
+
+/**
+ * User Implicit Configuration
+ *
+ * Explicit configuration takes precedence over implicit configuration.
+ * Implicit configuration are defined at decorators level.
+ */
+@Configuration()
+export class AppConfiguration implements IConfiguration {
+  /**
+   * Configure the application
+   *
+   * @param blueprint - The blueprint to configure
+   */
+  configure (blueprint: IBlueprint): Promiseable<void> {
+    blueprint
+      .set('database', this.databaseConfig())
+      .set('security', this.securityConfig())
+      .set('stone.logger.level', LogLevel.INFO)
+      .set('stone.http.cors.preflightStop', true)
+      .set('stone.http.cors.allowedHeaders', ['*'])
+      .set(defineBlueprintMiddleware(CORSHeadersMiddleware))
+  }
+
+  /**
+   * Get the database configuration
+   */
+  private databaseConfig (): Config {
+    return {
+      url: getString('DATABASE_URL', 'file:local.db')
+    }
+  }
+
+  /**
+   * Get the security configuration
+   */
+  private securityConfig (): Record<string, any> {
+    return {
+      jwt: {
+        expiresIn: 3600
+      },
+      secret: getString('SECURITY_JWT_SECRET', 'non_prod_secret'),
+      bcrypt: {
+        saltRounds: 10
+      }
+    }
+  }
+}

package/full-service-declarative/app/configurations/UserLiveConfiguration.ts

@@ -0,0 +1,28 @@
+import { Configuration, IBlueprint, IConfiguration } from '@stone-js/core'
+
+/**
+ * User Live Configuration
+ * Usefull for loading configuration without restarting the application.
+ * Live explicit configuration takes precedence over explicit and implicit configurations.
+ * Note: Only applicable for server applications.
+ */
+@Configuration({ live: true })
+export class UserLiveConfiguration implements IConfiguration {
+  /**
+   * Configure the application
+   *
+   * @param blueprint - The blueprint to configure
+   */
+  async configure (blueprint: IBlueprint): Promise<void> {
+    blueprint.set('stone.name', await this.fetchConfigurationRemotely())
+    console.log('I am live cause i am loaded at each request...')
+  }
+
+  /**
+   * Fetch the configuration remotely
+   */
+  async fetchConfigurationRemotely (): Promise<string> {
+    console.log('Fetching configuration...')
+    return await Promise.resolve('My Fetched app name')
+  }
+}

package/full-service-declarative/app/database/DatabaseClient.ts

@@ -0,0 +1,43 @@
+import { Client, Config, createClient } from '@libsql/client'
+
+/* eslint-disable @typescript-eslint/no-extraneous-class */
+
+/**
+ * DatabaseClient
+*/
+export class DatabaseClient {
+  private static _client?: Client
+
+  /**
+   * The client instance
+   */
+  static get client (): Client {
+    if (this._client === undefined) {
+      throw new Error('Database client is not initialized.')
+    }
+    return this._client
+  }
+
+  /**
+   * Create a new client instance
+   *
+   * @param config - The configuration object for the client
+   * @returns The client instance
+   */
+  static create (config: Config): Client {
+    if (this._client === undefined) {
+      this._client = createClient(config)
+    }
+    return this._client
+  }
+
+  /**
+   * Close the client instance
+   */
+  static close (): void {
+    if (this._client !== undefined) {
+      this._client.close()
+      this._client = undefined
+    }
+  }
+}

package/full-service-declarative/app/database/schema.ts

@@ -0,0 +1,43 @@
+import { sqliteTable, integer, text } from 'drizzle-orm/sqlite-core'
+
+// User Table
+export const users = sqliteTable('users', {
+  id: integer('id').primaryKey(),
+  name: text('name').notNull(),
+  password: text('password'),
+  avatar: text('avatar'),
+  email: text('email').unique().notNull(),
+  updatedAt: integer('updated_at').notNull(),
+  createdAt: integer('created_at').notNull() // Store timestamps as integers (Unix timestamp)
+})
+
+export const sessions = sqliteTable('sessions', {
+  id: integer('id').primaryKey(),
+  ip: text('ip').notNull(),
+  userAgent: text('user_agent'),
+  closedAt: integer('closed_at'),
+  uuid: text('uuid').unique().notNull(),
+  createdAt: integer('created_at').notNull(),
+  expiresAt: integer('expires_at').notNull(),
+  lastActivityAt: integer('last_activity_at').notNull(),
+  userId: integer('user_id').notNull().references(() => users.id, { onDelete: 'cascade' })
+})
+
+// Post Table
+export const posts = sqliteTable('posts', {
+  id: integer('id').primaryKey(),
+  title: text('title').notNull(),
+  content: text('content').notNull(),
+  createdAt: integer('created_at').notNull(),
+  updatedAt: integer('updated_at').notNull(),
+  authorId: integer('author_id').notNull().references(() => users.id, { onDelete: 'cascade' })
+})
+
+// Comment Table
+export const comments = sqliteTable('comments', {
+  id: integer('id').primaryKey(),
+  content: text('content').notNull(),
+  createdAt: integer('created_at').notNull(),
+  authorId: integer('author_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
+  postId: integer('post_id').notNull().references(() => posts.id, { onDelete: 'cascade' })
+})

package/full-service-declarative/app/error-handlers/SecurityErrorHandler.ts

@@ -0,0 +1,61 @@
+import { BadCredentialsError } from '../errors/CredentialsError'
+import { ErrorHandler, IErrorHandler, ILogger, Promiseable } from '@stone-js/core'
+import { BadRequestError, HTTP_BAD_REQUEST, HTTP_INTERNAL_SERVER_ERROR, HTTP_NOT_FOUND, HTTP_UNAUTHORIZED, IncomingHttpEvent, NotFoundError, UnauthorizedError } from '@stone-js/http-core'
+
+/**
+ * User Error Handler Options
+ */
+export interface SecurityErrorHandlerOptions {
+  logger: ILogger
+}
+
+/**
+ * User Error Handler
+ */
+@ErrorHandler({ error: ['BadCredentialsError', 'UnauthorizedError', 'NotFoundError', 'BadRequestError'] })
+export class SecurityErrorHandler implements IErrorHandler<IncomingHttpEvent> {
+  private readonly logger: ILogger
+
+  /**
+   * Create a new instance of SecurityErrorHandler
+   *
+   * @param logger
+   */
+  constructor ({ logger }: SecurityErrorHandlerOptions) {
+    this.logger = logger
+  }
+
+  /**
+   * Handle CredentialsError and UnauthorizedError
+   *
+   * @param error - The error to handle
+   * @param _event - The incoming event
+   * @returns The response
+   */
+  handle (error: BadCredentialsError | UnauthorizedError | NotFoundError | BadRequestError, _event: IncomingHttpEvent): Promiseable<unknown> {
+    this.logger.error(error.message)
+    let message: string = 'An error occurred'
+    let statusCode: number = HTTP_INTERNAL_SERVER_ERROR
+
+    if (error instanceof NotFoundError) {
+      message = error.message
+      statusCode = HTTP_NOT_FOUND
+    } else if (error instanceof BadCredentialsError) {
+      message = 'Invalid credentials'
+      statusCode = HTTP_UNAUTHORIZED
+    } else if (error instanceof UnauthorizedError) {
+      statusCode = HTTP_UNAUTHORIZED
+      message = 'You are not authorized to perform this action'
+    } else if (error instanceof BadRequestError) {
+      statusCode = HTTP_BAD_REQUEST
+      message = error.message
+    }
+
+    return {
+      statusCode,
+      content: {
+        errors: { message }
+      }
+    }
+  }
+}

package/full-service-declarative/app/errors/CredentialsError.ts

@@ -0,0 +1,12 @@
+import { ErrorOptions } from '@stone-js/core'
+import { UnauthorizedError } from '@stone-js/http-core'
+
+/**
+ * Bad Credentials Error
+ */
+export class BadCredentialsError extends UnauthorizedError {
+  constructor (message: string, options?: ErrorOptions) {
+    super(message, options)
+    this.name = 'BadCredentialsError'
+  }
+}