@stone-js/starters 0.8.3

package/full-service-declarative/app/subscribers/UserEventSubscriber.ts

@@ -0,0 +1,38 @@
+import { UserEvent } from '../events/UserEvent'
+import { EventEmitter, IEventSubscriber, ILogger, Subscriber } from '@stone-js/core'
+
+/**
+ * User Event Subscriber Options
+ */
+export interface UserEventSubscriberOptions {
+  logger: ILogger
+}
+
+/**
+ * User event subscriber
+ */
+@Subscriber()
+export class UserEventSubscriber implements IEventSubscriber {
+  private readonly logger: ILogger
+
+  /**
+   * Create a new instance of UserEventSubscriber
+   *
+   * @param logger
+   */
+  constructor ({ logger }: UserEventSubscriberOptions) {
+    this.logger = logger
+  }
+
+  /**
+   * Subscribe to user events
+   *
+   * @param eventEmitter - The event emitter
+   */
+  subscribe (eventEmitter: EventEmitter): void {
+    eventEmitter
+      .on(UserEvent.USER_CREATED, (event: UserEvent) => {
+        this.logger.info('User event subscriber', event.user)
+      })
+  }
+}

package/full-service-declarative/drizzle.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from 'drizzle-kit';
+
+/**
+ * Drizzle Configuration
+ */
+export default defineConfig({
+  out: './drizzle',
+  dialect: 'sqlite',
+  schema: './app/database/schema.ts',
+  dbCredentials: {
+    url: process.env.DB_FILE_NAME ?? 'file:local.db'
+  },
+})

package/full-service-declarative/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "full-service-declarative",
+  "private": true,
+  "version": "1.0.0",
+  "description": "Stone.js's full starter to create web app using declarative API.",
+  "author": "Mr. Stone <evensstone@gmail.com>",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "dev": "stone dev",
+    "build": "stone build",
+    "preview": "stone preview dist/server.mjs",
+    "typings": "stone typings",
+    "db:setup": "drizzle-kit push",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "test": "vitest run",
+    "test:cvg": "npm run test -- --coverage"
+  },
+  "dependencies": {
+    "@libsql/client": "^0.14.0",
+    "@stone-js/core": "^0.8.3",
+    "@stone-js/env": "^0.8.3",
+    "@stone-js/filesystem": "^0.8.3",
+    "@stone-js/http-core": "^0.8.3",
+    "@stone-js/node-cli-adapter": "^0.8.3",
+    "@stone-js/node-http-adapter": "^0.8.3",
+    "@stone-js/pipeline": "^0.8.3",
+    "@stone-js/router": "^0.8.3",
+    "bcryptjs": "^3.0.2",
+    "drizzle-orm": "^0.44.2",
+    "jsonwebtoken": "^9.0.2"
+  },
+  "devDependencies": {
+    "@babel/plugin-proposal-decorators": "^7.25.9",
+    "@babel/preset-env": "^7.26.9",
+    "@babel/preset-typescript": "^7.27.0",
+    "@stone-js/cli": "^0.8.3",
+    "@types/jsonwebtoken": "^9.0.8",
+    "@types/node": "^24.0.3",
+    "@vitest/coverage-v8": "^3.0.9",
+    "drizzle-kit": "^0.31.1",
+    "vitest": "^3.0.9"
+  }
+}

package/full-service-declarative/stone.config.mjs

@@ -0,0 +1,12 @@
+import { defineConfig } from '@stone-js/cli'
+
+/**
+ * Stone build configuration.
+ */
+export default defineConfig({
+  rollup: {
+    bundle: {
+      external: ['@libsql/client'],
+    }
+  }
+})

package/full-service-declarative/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "include": [
+    "app",
+    "tests",
+    ".stone",
+    "vitest.config.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ],
+  "compilerOptions": {
+    "strict": true,
+    "allowJs": false,
+    "target": "esnext",
+    "module": "ESNext",
+    "sourceMap": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "isolatedModules": true,
+    "resolveJsonModule": true,
+    "moduleResolution": "bundler",
+    "experimentalDecorators": true,
+    "types": ["node", "vitest/globals"],
+  }
+}

package/full-service-declarative/vitest.config.ts

@@ -0,0 +1,24 @@
+import { defineConfig } from 'vitest/config.js'
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['./tests/**/*.{test,spec}.?(c|m)[jt]s?(x)'],
+    coverage: {
+      provider: 'v8',
+      include: ['app/**/*.ts'],
+      reporter: ['text', 'html'],
+      reportsDirectory: './coverage',
+      thresholds: {
+        100: true
+      },
+      watermarks: {
+        statements: [60, 80],
+        functions: [60, 80],
+        branches: [60, 80],
+        lines: [60, 80]
+      }
+    },
+  }
+});

package/full-service-imperative/.env.example

@@ -0,0 +1,2 @@
+DB_FILE_NAME=
+BASE_URL=http://localhost:8080

package/full-service-imperative/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © 2026 Stone Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/full-service-imperative/README.md

@@ -0,0 +1,65 @@
+# Stone.js - Full starter
+
+Stone.js's full starter to create web app using imperative API.
+
+## Project Setup
+
+```sh
+npm install
+```
+
+### Compile and Hot-Reload for Development
+
+```sh
+npm run dev
+```
+
+### Compile and Bundle for Production
+
+```sh
+npm run build
+```
+
+### Run the Production build
+
+```sh
+npm run preview
+```
+
+### Run tests
+
+```sh
+npm run test
+```
+
+### Run tests with coverage
+
+```sh
+npm run test:cvg
+```
+
+## Database setup
+
+We use Drizzle ORM with SQLite for this starter. To set up the database, run:
+
+```sh
+npm run db:setup
+```
+
+This will create the necessary tables.
+
+### Database migrations
+
+To generate a new migration, use:
+
+```sh
+npm run db:generate
+```
+
+To apply database migrations, use:
+
+```sh
+npm run db:migrate
+```
+
+For more information on database management, refer to the [Drizzle ORM documentation](https://orm.drizzle.team/docs/).

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

@@ -0,0 +1,317 @@
+import {
+  IncomingHttpEvent,
+  OutgoingHttpResponse,
+  IncomingHttpEventOptions
+} from '@stone-js/http-core'
+import {
+  isEmpty,
+  LogLevel,
+  IContainer,
+  IBlueprint,
+  defineConfig,
+  AdapterConfig,
+  defineStoneApp,
+  AdapterContext,
+  BlueprintContext,
+  defineHookListener,
+  AdapterEventBuilderType,
+  AdapterHookListenerContext
+} from '@stone-js/core'
+import { getString } from '@stone-js/env'
+import { routerBlueprint } from '@stone-js/router'
+import { PipelineHookContext } from '@stone-js/pipeline'
+import { nodeConsoleAdapterBlueprint } from '@stone-js/node-cli-adapter'
+import { MetaBodyEventMiddleware, MetaFilesEventMiddleware, NODE_HTTP_PLATFORM, nodeHttpAdapterBlueprint } from '@stone-js/node-http-adapter'
+
+/**
+ * Run before the blueprint is prepared
+ *
+ * @param context - The blueprint context
+ */
+export const onPreparingBlueprint = defineHookListener(({ blueprint, modules }: BlueprintContext): void => {
+  blueprint.set('tmpBlueprintTimer', Date.now())
+  console.log(`Preparing blueprint by introspecting ${modules.length} modules...`)
+}, { name: 'onPreparingBlueprint' })
+
+/**
+ * Run before each blueprint middleware is processed
+ *
+ * @param context - The pipeline context
+ */
+export const onProcessingBlueprintMiddleware = defineHookListener(({ passable, pipe }: PipelineHookContext<BlueprintContext, IBlueprint>): void => {
+  passable.blueprint.set(`tmpBlueprintMiddleware.${String(pipe.module.name)}`, Date.now())
+}, { name: 'onProcessingBlueprintMiddleware' })
+
+/**
+ * Run after each blueprint middleware is processed
+ *
+ * @param context - The pipeline context
+ */
+export const onBlueprintMiddlewareProcessed = defineHookListener(({ 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)
+}, { name: 'onBlueprintMiddlewareProcessed' })
+
+/**
+ * Run after the blueprint is prepared
+ *
+ * @param context - The blueprint context
+ */
+export const onBlueprintPrepared = defineHookListener(({ 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)
+}, { name: 'onBlueprintPrepared' })
+
+/**
+ * Run before the application starts
+ *
+ * @param context - The adapter context
+ */
+export const onStart = defineHookListener(({ blueprint, context }: AdapterHookListenerContext): void => {
+  console.log('Starting application...')
+  console.log('Context isEmpty?', isEmpty(context))
+  console.log('Blueprint keys:', Object.keys(blueprint.all()).length)
+}, { name: 'onStart' })
+
+/**
+ * Run before each adapter middleware is processed
+ *
+ * @param context - The pipeline context
+ */
+export const onProcessingAdapterMiddleware = defineHookListener(({ 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))
+}, { name: 'onProcessingAdapterMiddleware' })
+
+/**
+ * Run after each adapter middleware is processed
+ *
+ * @param context - The pipeline context
+ */
+export const onAdapterMiddlewareProcessed = defineHookListener(({ 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))
+}, { name: 'onAdapterMiddlewareProcessed' })
+
+/**
+ * Run before building each incoming event
+ *
+ * @param context - The adapter context
+ */
+export const onBuildingIncomingEvent = defineHookListener(({ context }: AdapterHookListenerContext<
+AdapterContext<unknown, unknown, unknown, IncomingHttpEvent, IncomingHttpEventOptions, OutgoingHttpResponse>
+>): void => {
+  console.log('Building incoming event...')
+  console.log('IncomingEvent isEmpty?', isEmpty(context?.incomingEvent))
+}, { name: 'onBuildingIncomingEvent' })
+
+/**
+ * Run before handling each adapter error
+ *
+ * @param context - The adapter context
+ */
+export const onHandlingAdapterError = defineHookListener(({ error }: AdapterHookListenerContext<
+AdapterContext<unknown, unknown, unknown, IncomingHttpEvent, IncomingHttpEventOptions, OutgoingHttpResponse>
+>): void => {
+  console.error('Handling adapter error...')
+  console.error('Error:', error)
+}, { name: 'onHandlingAdapterError' })
+
+/**
+ * Run before building each outgoing response
+ *
+ * @param context - The adapter context
+ */
+export const onBuildingRawResponse = defineHookListener(({ 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))
+}, { name: 'onBuildingRawResponse' })
+
+/**
+ * Run just before the application stops
+ *
+ * @param context - The adapter context
+ */
+export const onStop = defineHookListener(({ blueprint, context }: AdapterHookListenerContext): void => {
+  console.log('Stopping application...')
+  console.log('Context isEmpty?', isEmpty(context))
+  console.log('Blueprint keys:', Object.keys(blueprint.all()).length)
+}, { name: 'onStop' })
+
+/**
+ * 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
+ */
+export const onInit = defineHookListener((container: IContainer): void => {
+  console.log('Initializing application...')
+  console.log('Container services count:', container.getBindings().size)
+}, { name: 'onInit' })
+
+/**
+ * Run before handling each event
+ *
+ * @param container - The container
+ */
+export const onHandlingEvent = defineHookListener((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)
+  }
+}, { name: 'onHandlingEvent' })
+
+/**
+ * Run before processing each kernel middleware
+ *
+ * @param context - The pipeline context
+ */
+export const onProcessingKernelMiddleware = defineHookListener((
+  { 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)
+}, { name: 'onProcessingKernelMiddleware' })
+
+/**
+ * Run after processing each kernel middleware
+ *
+ * @param context - The pipeline context
+ */
+export const onKernelMiddlewareProcessed = defineHookListener((
+  { 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)
+}, { name: 'onTerminate' })
+
+/**
+ * Run before executing each event handler
+ *
+ * @param container - The container
+ */
+export const onExecutingEventHandler = defineHookListener(({ event }: { event: IncomingHttpEvent }): void => {
+  console.log('Executing event handler...')
+  console.log('The incoming event is yet bound at this stage', event.source.platform)
+}, { name: 'onExecutingEventHandler' })
+
+/**
+ * Run before handling each error
+ *
+ * @param container - The container
+ */
+export const onExecutingErrorHandler = defineHookListener(({ error }: { error: any }): void => {
+  console.log('Executing error handler...')
+  console.log('Error', error)
+}, { name: 'onExecutingErrorHandler' })
+
+/**
+ * Run before preparing each response
+ *
+ * @param container - The container
+ */
+export const onPreparingResponse = defineHookListener(({ response }: { response: OutgoingHttpResponse }): void => {
+  console.log('Preparing response...')
+  console.log('Response headers', response.headers)
+}, { name: 'onPreparingResponse' })
+
+/**
+ * Run after preparing each response
+ *
+ * @param container - The container
+ */
+export const onResponsePrepared = defineHookListener(({ response }: { response: OutgoingHttpResponse }): void => {
+  console.log('Response prepared...')
+  console.log('Response headers', response.headers)
+}, { name: 'onResponsePrepared' })
+
+/**
+ * Run after handling each event
+ *
+ * @param context - The pipeline context
+ */
+export const onEventHandled = defineHookListener((
+  { event, response }: { event: IncomingHttpEvent, response: OutgoingHttpResponse }
+): void => {
+  console.log('Event handled...')
+  console.log('Event headers', event.headers)
+  console.log('Response headers', response.headers)
+}, { name: 'onEventHandled' })
+
+/**
+ * Run after executing each event handler
+ *
+ * @param container - The container
+ */
+export const onTerminate = defineHookListener((container: IContainer): void => {
+  console.log('Terminating event handling...')
+  console.log('Is IncomingEvent exist', container.bound('event'))
+  console.log('Is OutgoingResponse exist', container.bound('response'))
+}, { name: 'onTerminate' })
+
+/**
+ * Define Stone Application.
+ */
+export const Application = defineStoneApp(
+  { name: 'MyApp', logger: { level: LogLevel.INFO } },
+  [
+    routerBlueprint,
+    nodeHttpAdapterBlueprint,
+    nodeConsoleAdapterBlueprint
+  ]
+)
+
+/**
+ * Application configuration.
+ */
+export const AppConfig = defineConfig({
+  configure (blueprint: IBlueprint) {
+    blueprint
+      .get<AdapterConfig[]>('stone.adapters', [])
+      .forEach((adapter: AdapterConfig) => {
+        if (adapter.platform === NODE_HTTP_PLATFORM) {
+          adapter.default = true
+        }
+      })
+  },
+  afterConfigure (blueprint: IBlueprint) {
+    if (blueprint.is('stone.adapter.platform', NODE_HTTP_PLATFORM)) {
+      blueprint
+        .set('stone.adapter.url', getString('BASE_URL', 'http://localhost:8080'))
+        .add('stone.adapter.middleware', [MetaBodyEventMiddleware, MetaFilesEventMiddleware])
+    }
+  }
+})

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

@@ -0,0 +1,54 @@
+import { ILogger, IncomingEvent, isEmpty } from '@stone-js/core'
+import { IUserService } from '../services/contracts/IUserService'
+import { ISessionService } from '../services/contracts/ISessionService'
+import { CommandBuilder, defineCommand, FunctionalCommandHandler } from '@stone-js/node-cli-adapter'
+
+/**
+ * ListSessionsCommandOptions
+*/
+export interface ListSessionsCommandOptions {
+  logger: ILogger
+  userService: IUserService
+  sessionService: ISessionService
+}
+
+/**
+ * Factory List sessions command
+ */
+export function factoryListSessionsCommand ({ logger, sessionService, userService }: ListSessionsCommandOptions): FunctionalCommandHandler<IncomingEvent> {
+  return async function (event: IncomingEvent): Promise<void> {
+    const email = event.get<number>('email')
+    const limit = event.get<number>('limit', 10)
+    const user = isEmpty(email) ? undefined : await userService.findByEmail({ email })
+    const sessions = isEmpty(user)
+      ? await sessionService.list(limit)
+      : await sessionService.getByUser(user, limit)
+    logger.info('List sessions command')
+    console.table(sessions)
+  }
+}
+
+/**
+ * List sessions command
+ */
+export const ListSessionsCommand = defineCommand(factoryListSessionsCommand, {
+  alias: 'ls',
+  isFactory: true,
+  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'
+      })
+  }
+})

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

@@ -0,0 +1,42 @@
+import { ILogger, IncomingEvent } from '@stone-js/core'
+import { IUserService } from '../services/contracts/IUserService'
+import { CommandBuilder, defineCommand, FunctionalCommandHandler } from '@stone-js/node-cli-adapter'
+
+/**
+ * ListUsersCommandOptions
+*/
+export interface ListUsersCommandOptions {
+  logger: ILogger
+  userService: IUserService
+}
+
+/**
+ * Factory List users command
+ */
+export function factoryListUsersCommand ({ logger, userService }: ListUsersCommandOptions): FunctionalCommandHandler<IncomingEvent> {
+  return async function (event: IncomingEvent): Promise<void> {
+    const limit = event.get<number>('limit', 10)
+    const users = await userService.list(limit)
+    logger.info('List users command')
+    console.table(users)
+  }
+}
+
+/**
+ * List users command
+ */
+export const ListUsersCommand = defineCommand(factoryListUsersCommand, {
+  alias: 'lu',
+  isFactory: true,
+  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'
+      })
+  }
+})