@stone-js/starters 0.8.3

package/full-service-declarative/app/services/CommentService.ts

@@ -0,0 +1,112 @@
+import { NotFoundError } from '@stone-js/http-core'
+import { Comment, CommentModel } from '../models/Comment'
+import { IContainer, isNotEmpty, Service } from '@stone-js/core'
+import { CommentRepository } from '../repositories/CommentRepository'
+
+/**
+ * Comment Service Options
+ */
+export interface CommentServiceOptions {
+  commentRepository: CommentRepository
+}
+
+/**
+ * Comment Service
+ *
+ * Manages comment-related business logic.
+ */
+@Service({ alias: 'commentService' })
+export class CommentService {
+  private readonly commentRepository: CommentRepository
+
+  /**
+   * Resolve route binding.
+   *
+   * @param _key - The key of the binding.
+   * @param value - The value of the binding.
+   * @param container - The container instance.
+   */
+  static async resolveRouteBinding (_key: string, value: any, container: IContainer): Promise<Comment | undefined> {
+    const commentService = container.resolve<CommentService>('commentService')
+    return await commentService.findById(Number(value))
+  }
+
+  /**
+   * Create a new Comment Service.
+   */
+  constructor ({ commentRepository }: CommentServiceOptions) {
+    this.commentRepository = commentRepository
+  }
+
+  /**
+   * List comments.
+   *
+   * @param limit - The limit of comments to list.
+   */
+  async list (limit: number = 10): Promise<Comment[]> {
+    return await this.commentRepository.list({ limit })
+  }
+
+  /**
+   * Retrieve comments for a specific post.
+   *
+   * @param postId - The post ID.
+   * @param limit - The number of comments to retrieve.
+   */
+  async listByPost (postId: number, limit: number = 10): Promise<Comment[]> {
+    return await this.commentRepository.list({ postId, limit })
+  }
+
+  /**
+   * Retrieve comments by a specific user.
+   *
+   * @param authorId - The author ID.
+   * @param limit - The number of comments to retrieve.
+   */
+  async listByAuthor (authorId: number, limit: number = 10): Promise<Comment[]> {
+    return await this.commentRepository.list({ authorId, limit })
+  }
+
+  /**
+   * Find a comment by ID.
+   *
+   * @param id - The ID of the comment.
+   * @returns The found comment.
+   */
+  async findById (id: number): Promise<Comment> {
+    const comment = await this.commentRepository.findById(id)
+    if (isNotEmpty<CommentModel>(comment)) return comment
+    throw new NotFoundError(`Comment with ID ${id} not found`)
+  }
+
+  /**
+   * Create a new comment.
+   *
+   * @param payload - The comment data to create.
+   */
+  async create (payload: Omit<CommentModel, 'id'>): Promise<bigint | undefined> {
+    return await this.commentRepository.create({ ...payload, createdAt: Date.now() })
+  }
+
+  /**
+   * Update an existing comment.
+   *
+   * @param id - The ID of the comment.
+   * @param payload - The comment data to update.
+   * @returns The updated comment.
+   */
+  async update (id: number, payload: Partial<CommentModel>): Promise<Comment> {
+    const comment = await this.commentRepository.update(id, payload)
+    if (isNotEmpty<CommentModel>(comment)) return comment
+    throw new NotFoundError(`Comment with ID ${id} not found`)
+  }
+
+  /**
+   * Delete a comment.
+   *
+   * @param id - The ID of the comment.
+   */
+  async delete (id: number): Promise<boolean> {
+    return await this.commentRepository.delete(id)
+  }
+}

package/full-service-declarative/app/services/PostService.ts

@@ -0,0 +1,100 @@
+import { NotFoundError } from '@stone-js/http-core'
+import { PostRepository } from '../repositories/PostRepository'
+import { IContainer, isNotEmpty, Service } from '@stone-js/core'
+import { Post, PostCreateModel, PostModel } from '../models/Post'
+
+/**
+ * Post Service Options
+ */
+export interface PostServiceOptions {
+  postRepository: PostRepository
+}
+
+/**
+ * Post Service
+ *
+ * Manages post-related business logic.
+ */
+@Service({ alias: 'postService' })
+export class PostService {
+  private readonly postRepository: PostRepository
+
+  /**
+   * Resolve route binding.
+   *
+   * @param _key - The key of the binding.
+   * @param value - The value of the binding.
+   * @param container - The container instance.
+   */
+  static async resolveRouteBinding (_key: string, value: any, container: IContainer): Promise<Post | undefined> {
+    const postService = container.resolve<PostService>('postService')
+    return await postService.findById(Number(value))
+  }
+
+  /**
+   * Create a new Post Service.
+   */
+  constructor ({ postRepository }: PostServiceOptions) {
+    this.postRepository = postRepository
+  }
+
+  /**
+   * List posts.
+   *
+   * @param limit - The limit of posts to list.
+   */
+  async list (limit: number = 10): Promise<Post[]> {
+    return await this.postRepository.list({ limit })
+  }
+
+  /**
+   * Retrieve posts by a specific user.
+   *
+   * @param authorId - The author ID.
+   * @param limit - The number of posts to retrieve.
+   */
+  async listByAuthor (authorId: number, limit: number = 10): Promise<Post[]> {
+    return await this.postRepository.listByAuthor(authorId, limit)
+  }
+
+  /**
+   * Find a post by ID.
+   *
+   * @param id - The ID of the post.
+   * @returns The found post.
+   */
+  async findById (id: number): Promise<Post> {
+    const post = await this.postRepository.findById(id)
+    if (isNotEmpty<PostModel>(post)) return post
+    throw new NotFoundError(`Post with ID ${id} not found`)
+  }
+
+  /**
+   * Create a new post.
+   *
+   * @param payload - The post data to create.
+   */
+  async create (payload: Omit<PostCreateModel, 'id'>): Promise<bigint | undefined> {
+    return await this.postRepository.create({ ...payload, createdAt: Date.now(), updatedAt: Date.now() })
+  }
+
+  /**
+   * Update an existing post.
+   *
+   * @param id - The ID of the post.
+   * @param payload - The post data to update.
+   * @returns The updated post.
+   */
+  async update (id: number, payload: Partial<PostModel>): Promise<boolean> {
+    return await this.postRepository.update(id, payload)
+  }
+
+  /**
+   * Delete a post.
+   *
+   * @param id - The ID of the post.
+   */
+  async delete (id: number): Promise<boolean> {
+    return await this.postRepository.delete(id)
+  }
+}

package/full-service-declarative/app/services/SecurityService.ts

@@ -0,0 +1,232 @@
+import bcrypt from 'bcryptjs'
+import jwt from 'jsonwebtoken'
+import { SessionService } from './SessionService'
+import { UserRepository } from '../repositories/UserRepository'
+import { BadCredentialsError } from '../errors/CredentialsError'
+import { IBlueprint, isEmpty, isNotEmpty, Service } from '@stone-js/core'
+import { BadRequestError, IncomingHttpEvent, UnauthorizedError } from '@stone-js/http-core'
+import { UserLogin, UserToken, UserRegister, UserChangePassword, UserModel, UserTokenPayload } from '../models/User'
+
+/**
+ * Security Service Options
+*/
+export interface SecurityServiceOptions {
+  blueprint: IBlueprint
+  userRepository: UserRepository
+  sessionService: SessionService
+}
+
+/**
+ * Security Service
+ *
+ * @Service() decorator is used to define a new service
+ * @Service() is an alias of @Stone() decorator.
+ * The alias is required to get benefits of desctructuring Dependency Injection.
+ * And because the front-end class will be minified, we need to use alias to keep the class name.
+*/
+@Service({ alias: 'securityService' })
+export class SecurityService {
+  private readonly blueprint: IBlueprint
+  private readonly userRepository: UserRepository
+  private readonly sessionService: SessionService
+
+  /**
+   * Create a new Security Service
+  */
+  constructor ({ blueprint, userRepository, sessionService }: SecurityServiceOptions) {
+    this.blueprint = blueprint
+    this.userRepository = userRepository
+    this.sessionService = sessionService
+  }
+
+  /**
+   * Login a user
+   *
+   * @param credentials - The user to login
+   * @returns The user token
+  */
+  async login (event: IncomingHttpEvent, credentials: UserLogin): Promise<UserToken> {
+    const user = await this.userRepository.findBy(credentials)
+
+    if (isEmpty(user)) {
+      throw new BadCredentialsError(`The user with email ${credentials.email} does not exist`)
+    }
+
+    if (!(await this.comparePassword(credentials.password, user.password))) {
+      throw new BadCredentialsError('Invalid user password')
+    }
+
+    return {
+      tokenType: 'bearer',
+      expiresIn: this.blueprint.get<number>('security.jwt.expiresIn', 3600),
+      accessToken: await this.generateToken(user, event.ip, event.userAgent)
+    }
+  }
+
+  /**
+   * Refresh a token
+   *
+   * @param token - The token to refresh
+  */
+  async refresh (token: string): Promise<UserToken> {
+    const payload = this.verifyToken(token)
+    const user = await this.userRepository.findById(payload.user.id)
+
+    if (isEmpty(user)) {
+      throw new UnauthorizedError('User not found')
+    }
+
+    return {
+      tokenType: 'bearer',
+      expiresIn: this.blueprint.get<number>('security.jwt.expiresIn', 3600),
+      accessToken: await this.generateToken(user, payload.session.ip, payload.session.userAgent ?? undefined)
+    }
+  }
+
+  /**
+   * Logout a user
+   *
+   * @param token - The token to logout
+  */
+  async logout (token: string): Promise<void> {
+    const payload = this.verifyToken(token)
+    await this.sessionService.close(payload.session)
+  }
+
+  /**
+   * Authenticate a user
+   *
+   * @param token - The token to authenticate
+   * @returns The authenticated user
+  */
+  async authenticate (token: string, ip: string, userAgent?: string): Promise<UserModel> {
+    const payload = this.verifyToken(token)
+    const user = await this.userRepository.findById(payload.user.id)
+
+    if (payload.session.ip !== ip) {
+      throw new UnauthorizedError('Invalid IP address')
+    } else if (payload.session.userAgent !== userAgent) {
+      throw new UnauthorizedError('Invalid user agent')
+    } else if (isEmpty(user)) {
+      throw new UnauthorizedError('User not found')
+    }
+
+    await this.sessionService.updateLastActivity(payload.session)
+
+    return user
+  }
+
+  /**
+   * Hashes a password before storing it in the database.
+   *
+   * @param password - The plaintext password.
+   * @returns The hashed password.
+   */
+  async hashPassword (password: string): Promise<string> {
+    return await bcrypt.hash(password, this.blueprint.get<number>('security.bcrypt.saltRounds', 10))
+  }
+
+  /**
+   * Compares a plaintext password with a hashed password.
+   *
+   * @param password - The plaintext password.
+   * @param hashedPassword - The stored hashed password.
+   * @returns `true` if the password matches, otherwise `false`.
+   */
+  async comparePassword (password: string, hashedPassword?: string | null): Promise<boolean> {
+    return await bcrypt.compare(password, hashedPassword ?? '')
+  }
+
+  /**
+   * Generates a JWT token for a user.
+   *
+   * @param user - The user information to include in the token.
+   * @returns The generated JWT token.
+   */
+  async generateToken (user: UserModel, ip: string, userAgent?: string): Promise<string> {
+    let session = await this.sessionService.getLatest(user)
+
+    if (
+      isEmpty(session) ||
+      session?.ip !== ip ||
+      isNotEmpty(session.closedAt) ||
+      session?.userAgent !== userAgent
+    ) {
+      session = await this.sessionService.createForUser(user, ip, userAgent)
+    } else {
+      session = await this.sessionService.extend(
+        session,
+        this.blueprint.get<number>('security.jwt.expiresIn', 3600)
+      )
+    }
+
+    return jwt.sign(
+      {
+        user: {
+          ...user,
+          password: undefined
+        },
+        session
+      },
+      this.blueprint.get<string>('security.secret', 'secret'),
+      this.blueprint.get<jwt.SignOptions>('security.jwt')
+    )
+  }
+
+  /**
+   * Verifies a JWT token and returns the decoded payload.
+   *
+   * @param token - The JWT token to verify.
+   * @returns The decoded user payload or null if invalid.
+   */
+  verifyToken = (token: string): UserTokenPayload => {
+    try {
+      return jwt.verify(
+        token,
+        this.blueprint.get<string>('security.secret', 'secret')
+      ) as UserTokenPayload
+    } catch (error: any) {
+      throw new UnauthorizedError('Invalid token', { cause: error })
+    }
+  }
+
+  /**
+   * Register a user
+   *
+   * @param user - The user to register
+  */
+  async register (payload: UserRegister): Promise<void> {
+    const user = await this.userRepository.findBy({ email: payload.email })
+
+    if (isNotEmpty(user)) {
+      throw new BadRequestError(`The user with email ${payload.email} already exists`)
+    }
+
+    const password = await this.hashPassword(payload.password)
+
+    await this.userRepository.create({
+      ...payload,
+      password,
+      updatedAt: Date.now(),
+      createdAt: Date.now()
+    })
+  }
+
+  /**
+   * Change the user password
+   *
+   * @param user - The user to change the password
+   * @param password - The password to change
+  */
+  async changePassword (user?: UserModel, password?: UserChangePassword): Promise<void> {
+    if (isEmpty(user)) {
+      throw new UnauthorizedError('User not found')
+    }
+
+    if (isEmpty(password) || !(await this.comparePassword(password.password, user.password))) {
+      throw new UnauthorizedError('Invalid user password')
+    }
+
+    await this.userRepository.update(user.id, { password: password.newPassword })
+  }
+}

package/full-service-declarative/app/services/SessionService.ts

@@ -0,0 +1,130 @@
+import { Service } from '@stone-js/core'
+import { randomUUID } from 'node:crypto'
+import { UserModel } from '../models/User'
+import { Session } from '../models/Session'
+import { SessionRepository } from '../repositories/SessionRepository'
+
+/**
+ * Session Service Options
+ */
+export interface SessionServiceOptions {
+  sessionRepository: SessionRepository
+}
+
+/**
+ * Session Service
+ *
+ * @Service() decorator is used to define a new service
+ * @Service() is an alias of @Stone() decorator.
+ * The alias is required to get benefits of desctructuring Dependency Injection.
+ * And because the front-end class will be minified, we need to use alias to keep the class name.
+*/
+@Service({ alias: 'sessionService' })
+export class SessionService {
+  private readonly sessionRepository: SessionRepository
+
+  /**
+   * Create a new Session Service
+   *
+   * @param options - The options to create the service
+  */
+  constructor ({ sessionRepository }: SessionServiceOptions) {
+    this.sessionRepository = sessionRepository
+  }
+
+  /**
+   * Finds all sessions.
+   *
+   * @param limit - The limit of sessions to list
+   * @returns The list of sessions
+   */
+  async list (limit: number): Promise<Session[]> {
+    return await this.sessionRepository.list(limit)
+  }
+
+  /**
+   * Finds a sessions by user.
+   *
+   * @param user - The user to look up
+   * @param limit - The limit of sessions to list
+   * @returns The list of sessions
+   */
+  async getByUser (user: UserModel, limit: number): Promise<Session[]> {
+    return await this.sessionRepository.listByUser(user, limit)
+  }
+
+  /**
+   * Finds a session by ID.
+   *
+   * @param sessionId - The session ID to look up
+   * @returns The session data or `undefined` if not found
+   */
+  async getById (id: number): Promise<Session | undefined> {
+    return await this.sessionRepository.findById(id)
+  }
+
+  /**
+   * Finds the latest session of a user.
+   *
+   * @param user - The user to look up
+   * @returns The latest session or `undefined` if not found
+   */
+  async getLatest (user: UserModel): Promise<Session | undefined> {
+    return await this.sessionRepository.getLatest(user)
+  }
+
+  /**
+   * Creates a new session for a user.
+   *
+   * @param user - The user to create the session for
+   * @param ip - The IP address of the user
+   * @param userAgent - The user agent of the user
+   * @returns The created session
+  */
+  async createForUser (user: UserModel, ip: string, userAgent?: string): Promise<Session> {
+    const session = {
+      ip,
+      userAgent,
+      userId: user.id,
+      createdAt: Date.now(),
+      uuid: randomUUID(),
+      lastActivityAt: Date.now(),
+      expiresAt: Date.now() + 3600
+    }
+
+    return await this.sessionRepository.create(session)
+  }
+
+  /**
+   * Updates the last activity timestamp of a session.
+   *
+   * @param sessionId - The session ID to update
+   * @returns `true` if the session was updated, otherwise `false`
+   */
+  async updateLastActivity (session: Session): Promise<void> {
+    await this.sessionRepository.update(session.id, { lastActivityAt: Date.now() })
+  }
+
+  /**
+   * Extends a session expiration time.
+   *
+   * @param sessionId - The session ID to extend
+   * @param additionalTime - Additional time in milliseconds
+   * @returns `true` if the session was extended, otherwise `false`
+   */
+  async extend (session: Session, additionalTime: number): Promise<Session> {
+    session.expiresAt = Date.now() + additionalTime
+    await this.sessionRepository.update(session.id, session)
+    return session
+  }
+
+  /**
+   * Closes a session.
+   *
+   * @param sessionId - The session ID to close
+   */
+  async close (session: Session): Promise<void> {
+    session.closedAt = Date.now()
+    await this.sessionRepository.update(session.id, session)
+  }
+}

package/full-service-declarative/app/services/UserService.ts

@@ -0,0 +1,110 @@
+import { UserModel } from '../models/User'
+import { UserEvent } from '../events/UserEvent'
+import { NotFoundError } from '@stone-js/http-core'
+import { UserRepository } from '../repositories/UserRepository'
+import { EventEmitter, IContainer, isNotEmpty, Service } from '@stone-js/core'
+
+/**
+ * User Service Options
+*/
+export interface UserServiceOptions {
+  eventEmitter: EventEmitter
+  userRepository: UserRepository
+}
+
+/**
+ * User Service
+ *
+ * @Service() decorator is used to define a new service
+ * @Service() is an alias of @Stone() decorator.
+ * The alias is required to get benefits of desctructuring Dependency Injection.
+ * And because the front-end class will be minified, we need to use alias to keep the class name.
+*/
+@Service({ alias: 'userService' })
+export class UserService {
+  private readonly eventEmitter: EventEmitter
+  private readonly userRepository: UserRepository
+
+  /**
+   * Resolve route binding
+   *
+   * @param key - The key of the binding
+   * @param value - The value of the binding
+   * @param container - The container
+   */
+  static async resolveRouteBinding (key: string, value: any, container: IContainer): Promise<UserModel | undefined> {
+    const userService = container.resolve<UserService>('userService')
+    return await userService.findBy({ [key]: value })
+  }
+
+  /**
+   * Create a new User Service
+  */
+  constructor ({ userRepository, eventEmitter }: UserServiceOptions) {
+    this.eventEmitter = eventEmitter
+    this.userRepository = userRepository
+  }
+
+  /**
+   * List users
+   *
+   * @param limit - The limit of users to list
+   */
+  async list (limit: number = 10): Promise<UserModel[]> {
+    return await this.userRepository.list(limit)
+  }
+
+  /**
+   * Find a user
+   *
+   * @param conditions - The conditions to find the user
+   * @returns The found user
+   */
+  async findBy (conditions: Record<string, any>): Promise<UserModel> {
+    const user = await this.userRepository.findById(conditions.id)
+    if (isNotEmpty<UserModel>(user)) return user
+    throw new NotFoundError(`User with ID ${String(conditions.id)} not found`)
+  }
+
+  /**
+   * Find a user
+   *
+   * @param conditions - The conditions to find the user
+   * @returns The found user
+   */
+  async findByEmail (conditions: Record<string, any>): Promise<UserModel | undefined> {
+    return await this.userRepository.findBy(conditions)
+  }
+
+  /**
+   * Create a user
+   *
+   * @param payload - The user data to create
+   */
+  async create (payload: Omit<UserModel, 'id'>): Promise<bigint | undefined> {
+    await this.eventEmitter.emit(new UserEvent(payload))
+    return await this.userRepository.create({ ...payload, createdAt: Date.now(), updatedAt: Date.now() })
+  }
+
+  /**
+   * Update a user
+   *
+   * @param id - The id of the user to update
+   * @param payload - The user data to update
+   * @returns The updated user
+   */
+  async update (id: number, payload: UserModel): Promise<UserModel> {
+    const user = await this.userRepository.update(id, payload)
+    if (isNotEmpty<UserModel>(user)) return user
+    throw new NotFoundError(`User with ID ${id} not found`)
+  }
+
+  /**
+   * Delete a user
+   *
+   * @param id - The id of the user to delete
+   */
+  async delete (id: number): Promise<boolean> {
+    return await this.userRepository.delete(id)
+  }
+}