@stone-js/starters 0.8.3

package/full-service-imperative/app/services/contracts/ISessionService.ts

@@ -0,0 +1,73 @@
+import { UserModel } from '../../models/User'
+import { Session } from '../../models/Session'
+
+/**
+ * Session Service contract
+ */
+export interface ISessionService {
+  /**
+   * Finds all sessions.
+   *
+   * @param limit - The limit of sessions to list.
+   * @returns The list of sessions.
+   */
+  list: (limit: number) => Promise<Session[]>
+
+  /**
+   * Finds sessions by user.
+   *
+   * @param user - The user to look up.
+   * @param limit - The limit of sessions to list.
+   * @returns The list of sessions.
+   */
+  getByUser: (user: UserModel, limit: number) => Promise<Session[]>
+
+  /**
+   * Finds a session by ID.
+   *
+   * @param id - The session ID to look up.
+   * @returns The session or `undefined` if not found.
+   */
+  getById: (id: number) => Promise<Session | undefined>
+
+  /**
+   * Finds the latest session of a user.
+   *
+   * @param user - The user to look up.
+   * @returns The latest session or `undefined`.
+   */
+  getLatest: (user: UserModel) => Promise<Session | undefined>
+
+  /**
+   * Creates a new session for a user.
+   *
+   * @param user - The user to create the session for.
+   * @param ip - The user's IP address.
+   * @param userAgent - Optional user agent string.
+   * @returns The created session.
+   */
+  createForUser: (user: UserModel, ip: string, userAgent?: string) => Promise<Session>
+
+  /**
+   * Updates the last activity timestamp of a session.
+   *
+   * @param session - The session to update.
+   */
+  updateLastActivity: (session: Session) => Promise<void>
+
+  /**
+   * Extends the expiration time of a session.
+   *
+   * @param session - The session to extend.
+   * @param additionalTime - The additional time in milliseconds.
+   * @returns The updated session.
+   */
+  extend: (session: Session, additionalTime: number) => Promise<Session>
+
+  /**
+   * Closes a session.
+   *
+   * @param session - The session to close.
+   */
+  close: (session: Session) => Promise<void>
+}

package/full-service-imperative/app/services/contracts/IUserService.ts

@@ -0,0 +1,57 @@
+import { UserModel } from '../../models/User'
+
+/**
+ * User Service contract
+ */
+export interface IUserService {
+  /**
+   * List users.
+   *
+   * @param limit - The limit of users to list.
+   * @returns A list of users.
+   */
+  list: (limit?: number) => Promise<UserModel[]>
+
+  /**
+   * Find a user by conditions.
+   *
+   * @param conditions - The conditions to find the user (e.g., by ID).
+   * @returns The found user.
+   * @throws NotFoundError if user is not found.
+   */
+  findBy: (conditions: Record<string, any>) => Promise<UserModel>
+
+  /**
+   * Find a user by email or other unique field.
+   *
+   * @param conditions - The conditions (typically email).
+   * @returns The user or `undefined` if not found.
+   */
+  findByEmail: (conditions: Record<string, any>) => Promise<UserModel | undefined>
+
+  /**
+   * Create a new user.
+   *
+   * @param payload - The user data to create.
+   * @returns The ID of the created user.
+   */
+  create: (payload: Omit<UserModel, 'id'>) => Promise<bigint | undefined>
+
+  /**
+   * Update a user.
+   *
+   * @param id - The user ID.
+   * @param payload - The updated user data.
+   * @returns The updated user.
+   * @throws NotFoundError if the user is not found.
+   */
+  update: (id: number, payload: UserModel) => Promise<UserModel>
+
+  /**
+   * Delete a user.
+   *
+   * @param id - The user ID.
+   * @returns `true` if the user was deleted, `false` otherwise.
+   */
+  delete: (id: number) => Promise<boolean>
+}

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

@@ -0,0 +1,28 @@
+import { UserEvent } from '../events/UserEvent'
+import { defineEventSubscriber, EventEmitter, FunctionalEventSubscriber, ILogger } from '@stone-js/core'
+
+/**
+ * User Event Subscriber Options
+ */
+export interface UserEventSubscriberOptions {
+  logger: ILogger
+}
+
+/**
+ * Subscribe to user events
+ *
+ * @param eventEmitter - The event emitter
+ */
+export function FactoryUserEventSubscriber ({ logger }: UserEventSubscriberOptions): FunctionalEventSubscriber {
+  return (eventEmitter: EventEmitter): void => {
+    eventEmitter
+      .on(UserEvent.USER_CREATED, (event: UserEvent) => {
+        logger.info('User event subscriber', event.user)
+      })
+  }
+}
+
+/**
+ * User event subscriber
+ */
+export const UserEventSubscriber = defineEventSubscriber(FactoryUserEventSubscriber, { isFactory: true })

package/full-service-imperative/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-imperative/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "full-service-imperative",
+  "private": true,
+  "version": "1.0.0",
+  "description": "Stone.js's full starter to create web app using imperative 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-imperative/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-imperative/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-imperative/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/package.json

@@ -0,0 +1,225 @@
+{
+  "name": "@stone-js/starters",
+  "version": "0.8.3",
+  "description": "This repository contains official **starter templates** for Stone.js applications.",
+  "author": "Mr. Stone <evensstone@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stone-foundation/stone-js-framework.git",
+    "directory": "stone-js-starters"
+  },
+  "homepage": "https://stonejs.dev",
+  "bugs": {
+    "url": "https://github.com/stone-foundation/stone-js-framework/issues"
+  },
+  "keywords": [
+    "Starters",
+    "Scaffolding",
+    "Stone.js"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=18.17.0"
+  },
+  "stone": {
+    "starters": [
+      {
+        "value": "basic-service-declarative",
+        "title": "Basic · service · declarative",
+        "description": "Minimal HTTP/service API, decorator API.",
+        "tags": [
+          "api",
+          "service",
+          "basic",
+          "declarative"
+        ],
+        "path": "basic-service-declarative"
+      },
+      {
+        "value": "basic-service-imperative",
+        "title": "Basic · service · imperative",
+        "description": "Minimal HTTP/service API, imperative API.",
+        "tags": [
+          "api",
+          "service",
+          "basic",
+          "imperative"
+        ],
+        "path": "basic-service-imperative"
+      },
+      {
+        "value": "basic-react-declarative",
+        "title": "Basic · React · declarative",
+        "description": "Minimal React SPA, decorator API.",
+        "tags": [
+          "react",
+          "spa",
+          "basic",
+          "declarative"
+        ],
+        "path": "basic-react-declarative"
+      },
+      {
+        "value": "basic-react-imperative",
+        "title": "Basic · React · imperative",
+        "description": "Minimal React SPA, imperative API.",
+        "tags": [
+          "react",
+          "spa",
+          "basic",
+          "imperative"
+        ],
+        "path": "basic-react-imperative"
+      },
+      {
+        "value": "standard-service-declarative",
+        "title": "Standard · service · declarative",
+        "description": "Common service setup, decorator API.",
+        "tags": [
+          "api",
+          "service",
+          "standard",
+          "declarative"
+        ],
+        "path": "standard-service-declarative"
+      },
+      {
+        "value": "standard-service-imperative",
+        "title": "Standard · service · imperative",
+        "description": "Common service setup, imperative API.",
+        "tags": [
+          "api",
+          "service",
+          "standard",
+          "imperative"
+        ],
+        "path": "standard-service-imperative"
+      },
+      {
+        "value": "standard-react-declarative",
+        "title": "Standard · React · declarative (SSR)",
+        "description": "React with SSR, decorator API.",
+        "tags": [
+          "react",
+          "ssr",
+          "standard",
+          "declarative"
+        ],
+        "path": "standard-react-declarative"
+      },
+      {
+        "value": "standard-react-imperative",
+        "title": "Standard · React · imperative (SSR)",
+        "description": "React with SSR, imperative API.",
+        "tags": [
+          "react",
+          "ssr",
+          "standard",
+          "imperative"
+        ],
+        "path": "standard-react-imperative"
+      },
+      {
+        "value": "full-service-declarative",
+        "title": "Full · service · declarative",
+        "description": "Full-featured service, decorator API.",
+        "tags": [
+          "api",
+          "service",
+          "full",
+          "declarative"
+        ],
+        "path": "full-service-declarative"
+      },
+      {
+        "value": "full-service-imperative",
+        "title": "Full · service · imperative",
+        "description": "Full-featured service, imperative API.",
+        "tags": [
+          "api",
+          "service",
+          "full",
+          "imperative"
+        ],
+        "path": "full-service-imperative"
+      },
+      {
+        "value": "full-react-declarative",
+        "title": "Full · React · declarative (SSR/SSG)",
+        "description": "Full React with SSR & SSG, decorator API.",
+        "tags": [
+          "react",
+          "ssr",
+          "ssg",
+          "full",
+          "declarative"
+        ],
+        "path": "full-react-declarative"
+      },
+      {
+        "value": "full-react-imperative",
+        "title": "Full · React · imperative (SSR/SSG)",
+        "description": "Full React with SSR & SSG, imperative API.",
+        "tags": [
+          "react",
+          "ssr",
+          "ssg",
+          "full",
+          "imperative"
+        ],
+        "path": "full-react-imperative"
+      },
+      {
+        "value": "continuum-showcase",
+        "title": "Continuum showcase",
+        "description": "One domain served over HTTP, edge, CLI and agent tools, both paradigms side by side.",
+        "tags": [
+          "showcase",
+          "continuum",
+          "full"
+        ],
+        "path": "continuum-showcase"
+      }
+    ]
+  },
+  "scripts": {
+    "lint": "ts-standard **/app",
+    "lint:fix": "ts-standard --fix **/app",
+    "prepare": "husky"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^19.8.1",
+    "@commitlint/config-conventional": "^19.8.1",
+    "husky": "^9.1.7",
+    "ts-standard": "^12.0.2",
+    "tslib": "^2.8.1",
+    "typescript": "^5.6.3"
+  },
+  "ts-standard": {
+    "globals": [
+      "it",
+      "expect",
+      "describe",
+      "beforeEach"
+    ]
+  },
+  "files": [
+    "basic-service-declarative",
+    "basic-service-imperative",
+    "basic-react-declarative",
+    "basic-react-imperative",
+    "standard-service-declarative",
+    "standard-service-imperative",
+    "standard-react-declarative",
+    "standard-react-imperative",
+    "full-service-declarative",
+    "full-service-imperative",
+    "full-react-declarative",
+    "full-react-imperative",
+    "continuum-showcase"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/standard-react-declarative/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/standard-react-declarative/README.md

@@ -0,0 +1,39 @@
+# Stone.js - Standard starter
+
+Stone.js's standard starter to create react app using declarative 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
+```

package/standard-react-declarative/app/Application.ts

@@ -0,0 +1,45 @@
+import { Routing } from '@stone-js/router'
+import { UseReact } from '@stone-js/use-react'
+import { Browser } from '@stone-js/browser-adapter'
+import { NodeHttp } from '@stone-js/node-http-adapter'
+import { StoneApp, AdapterHookListenerContext, Hook, LogLevel, Logger } from '@stone-js/core'
+
+/**
+ * Application
+ *
+ * This is the main application entry point.
+ *
+ * @UseReact() is used to enable the React.
+ * @Browser() is used to enable the Browser adapter.
+ * @Routing() is used to enable the routing feature.
+ * @NodeHttp() is used to enable the Node HTTP adapter.
+ * @StoneApp() is used to enable the Stone application, it is required.
+ *
+ * Lifecycle hooks are used here just for demonstration purposes.
+ */
+@Routing()
+@Browser()
+@UseReact()
+@NodeHttp({ default: true })
+@StoneApp({ name: 'MyApp', logger: { level: LogLevel.INFO } })
+export class Application {
+  /**
+   * Run before the application starts
+   *
+   * @param blueprint - The blueprint
+   */
+  @Hook('onStart')
+  onStart ({ blueprint }: AdapterHookListenerContext): void {
+    Logger.log(`${String(blueprint.get('stone.name', 'Stone App'))} is starting...`)
+  }
+
+  /**
+   * Run just before the application stops
+   *
+   * @param blueprint - The blueprint
+   */
+  @Hook('onStop')
+  onStop ({ blueprint }: AdapterHookListenerContext): void {
+    Logger.log(`${String(blueprint.get('stone.name', 'Stone App'))} is stopping...`)
+  }
+}

package/standard-react-declarative/app/pages/welcome/WelcomePage.tsx

@@ -0,0 +1,57 @@
+import { JSX } from 'react'
+import { WelcomeService } from '../../services/WelcomeService'
+import { Page, ReactIncomingEvent, PageRenderContext, IPage } from '@stone-js/use-react'
+
+/**
+ * WelcomePage Options
+*/
+export interface WelcomePageOptions {
+  welcomeService: WelcomeService
+}
+
+/**
+ * Response data
+ */
+export interface ResponseData {
+  message: string
+}
+
+/**
+ * Welcome Page component.
+ */
+@Page('/:name?')
+export class WelcomePage implements IPage<ReactIncomingEvent> {
+  private readonly welcomeService: WelcomeService
+
+  /**
+   * Create a new instance of WelcomePage
+   *
+   * @param welcomeService
+   */
+  constructor ({ welcomeService }: WelcomePageOptions) {
+    this.welcomeService = welcomeService
+  }
+
+  /**
+   * Handle the incoming event.
+   *
+   * @param event - The incoming event.
+   * @returns A welcome message
+  */
+  handle (event: ReactIncomingEvent): ResponseData {
+    return this.welcomeService.welcome(event.get<string>('name', 'World'))
+  }
+
+  /**
+   * Render the component.
+   *
+   * @returns The rendered component.
+   */
+  render ({ data }: PageRenderContext<ResponseData>): JSX.Element {
+    return (
+      <section className='container'>
+        <h1 className='h1 text-center mt-64'>{data?.message}</h1>
+      </section>
+    )
+  }
+}