@lakutata/template-default 3.0.0-beta.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2023-present Lakutata
+
+All rights reserved
+
+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/README.md

@@ -0,0 +1,11 @@
+# @lakutata/template-default
+
+The default template of the [lakutata](https://github.com/lakutata/lakutata) projects: a minimal application whose
+controller serves HTTP actions with the express adapter.
+
+```bash
+npx @lakutata/cli create --name my-app
+```
+
+The files of the project are in `template/`; `lakutata create` fills `{$APP_NAME}`, `{$APP_ID}`, `{$APP_DESC}`,
+`{$APP_AUTHOR}` and `{$APP_LICENSE}`, and renames `_gitignore` to `.gitignore`.

package/features/i18n/package.json

@@ -0,0 +1,6 @@
+{
+  "scripts": {
+    "i18n:check": "lakutata i18n check --dir src/locales",
+    "i18n:types": "lakutata i18n types --dir src/locales"
+  }
+}

package/features/i18n/src/locales/en.json

@@ -0,0 +1,5 @@
+{
+  "greeting": {
+    "hello": "Hello, {name}!"
+  }
+}

package/features/i18n/src/locales/zh-CN.json

@@ -0,0 +1,5 @@
+{
+  "greeting": {
+    "hello": "你好，{name}！"
+  }
+}

package/features/i18n/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "compilerOptions": {
+    "resolveJsonModule": true
+  }
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@lakutata/template-default",
+  "version": "3.0.0-beta.0",
+  "description": "The default template of the lakutata projects: a minimal application serving HTTP actions.",
+  "keywords": [
+    "lakutata",
+    "lakutata-template"
+  ],
+  "license": "MIT",
+  "files": [
+    "template",
+    "features",
+    "README.md",
+    "LICENSE"
+  ],
+  "lakutata": {
+    "template": "default",
+    "features": {
+      "i18n": "The messages in several languages (lakutata/com/i18n): src/locales, the language of each request"
+    }
+  }
+}

package/template/README.md

@@ -0,0 +1,48 @@
+# {$APP_NAME}
+
+{$APP_DESC}
+
+A [lakutata](https://github.com/lakutata/lakutata) application.
+
+```bash
+npm run dev     # build and start, http://localhost:8080/example
+npm test        # build and run the tests
+npm run build   # compile into build/
+npm start       # start the compiled application
+```
+
+- `src/App.ts` starts the application;
+- `src/config/Config.ts` declares its components, the entrypoint and its adapters;
+- `src/controllers/` holds the controllers: their actions are served by the adapters of the entrypoint.
+
+## Database migrations
+
+```bash
+npm run migration:generate              # the migrations of the changes of the entities of the databases
+npm run migration:create -- seed-users  # an empty migration, written by hand
+npm run migration:show                  # the migrations run [X] and pending [ ]
+npm run migration:run                   # run the pending migrations
+npm run migration:revert                # revert the last migration run
+```
+
+The commands (`lakutata migration <action>`) build and start the application, which connects its databases with their
+options (without synchronizing their schemas), does the command and exits; `-- --database <name>` selects a database
+(required to revert when there are several), `-- --fake` marks the migrations as run or reverted without executing
+them. The migrations are written into `src/migrations`, compiled with the application and given to the options of the
+databases, run when they connect:
+
+```typescript
+import {buildDatabaseOptions} from 'lakutata/com/database'
+import {Migrations1788773616343} from '../migrations/1788773616343-db.js'
+
+components: {
+    db: buildDatabaseOptions({
+        type: 'postgres',
+        url: process.env.DATABASE_URL,
+        entities: [/* the entities */],
+        synchronize: false,
+        migrationsRun: true,
+        migrations: [Migrations1788773616343]
+    })
+}
+```

package/template/_gitignore

@@ -0,0 +1,8 @@
+node_modules
+/build
+*.log
+.env.local
+.env.*.local
+.DS_Store
+.idea
+.vscode

package/template/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "{$APP_ID}",
+  "version": "0.0.1",
+  "description": "{$APP_DESC}",
+  "author": "{$APP_AUTHOR}",
+  "license": "{$APP_LICENSE}",
+  "private": true,
+  "type": "module",
+  "main": "build/App.js",
+  "scripts": {
+    "clean": "lakutata clean",
+    "build": "npm run clean && tsc",
+    "start": "node build/App.js",
+    "dev": "npm run build && node build/App.js",
+    "migration:generate": "lakutata migration generate",
+    "migration:create": "lakutata migration create",
+    "migration:run": "lakutata migration run",
+    "migration:revert": "lakutata migration revert",
+    "migration:show": "lakutata migration show",
+    "test": "npm run build && node --test \"build/tests/**/*.spec.js\""
+  },
+  "dependencies": {
+    "express": "^5.2.1",
+    "lakutata": "^{$LAKUTATA_VERSION}"
+  },
+  "devDependencies": {
+    "@lakutata/cli": "^{$LAKUTATA_VERSION}",
+    "@types/express": "^5.0.6",
+    "@types/node": "^22.0.0",
+    "typescript": "^6.0.3"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/template/src/App.ts

@@ -0,0 +1,7 @@
+import {Application, type ILogger} from 'lakutata'
+import {installerConfig} from './config/Config.js'
+
+Application
+    .run(installerConfig)
+    .onLaunched((app: Application, log: ILogger): void => log.info('%s started in %s mode', app.appName, app.mode()))
+    .onFatalException((error: Error, log: ILogger): void => log.error('The application cannot start: %s', error.message))

package/template/src/config/Config.ts

@@ -0,0 +1,36 @@
+import type {ApplicationOptions} from 'lakutata'
+import {buildEntrypoints} from 'lakutata/com/entrypoint'
+import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
+import {ExampleController} from '../controllers/ExampleController.js'
+//@if i18n
+import {buildI18nOptions, I18nMiddleware} from 'lakutata/com/i18n'
+import en from '../locales/en.json' with {type: 'json'}
+import zhCN from '../locales/zh-CN.json' with {type: 'json'}
+//@end
+
+/**
+ * The options of the application
+ * @param port the port of the HTTP server, the PORT environment variable or 8080 by default
+ */
+export function installerConfig(port: number = Number(process.env.PORT ?? 8080)): ApplicationOptions {
+    return {
+        id: '{$APP_ID}',
+        name: '{$APP_NAME}',
+        mode: process.env.NODE_ENV === 'production' ? 'production' : 'development',
+        components: {
+            //@if i18n
+            //The messages of the languages (src/locales), bundled with the code; created by the first request
+            i18n: buildI18nOptions({messages: {'en': en, 'zh-CN': zhCN}}),
+            //@end
+            entrypoint: buildEntrypoints({
+                controllers: [ExampleController],
+                //@if i18n
+                //The messages in the language of each request: ?lang=, the cookie lang, Accept-Language
+                middlewares: [I18nMiddleware],
+                //@end
+                http: expressHTTPEntrypoint({port: port})
+            })
+        },
+        bootstrap: ['entrypoint']
+    }
+}

package/template/src/controllers/ExampleController.ts

@@ -0,0 +1,32 @@
+import {Controller} from 'lakutata/com/entrypoint'
+import {CLIAction, GET} from 'lakutata/decorator/ctrl'
+import {GreetDTO} from '../dtos/GreetDTO.js'
+//@if i18n
+import {Inject} from 'lakutata/decorator/di'
+import {Translator} from 'lakutata/com/i18n'
+//@end
+
+export class ExampleController extends Controller {
+    //@if i18n
+
+    /**
+     * The messages of the language of the request
+     */
+    @Inject(Translator)
+    protected readonly i18n: Translator
+    //@end
+
+    /**
+     * GET /example?name=you, or the command "greet --name you" with a CLI adapter
+     * @param input
+     */
+    @GET('/example', GreetDTO)
+    @CLIAction('greet', GreetDTO)
+    public async greet(input: GreetDTO): Promise<{ message: string }> {
+        //@if i18n
+        return {message: this.i18n.t('greeting.hello', {name: input.name})}
+        //@else
+        return {message: `Hello, ${input.name}!`}
+        //@end
+    }
+}

package/template/src/dtos/GreetDTO.ts

@@ -0,0 +1,7 @@
+import {DTO} from 'lakutata'
+import {Expect} from 'lakutata/decorator/dto'
+
+export class GreetDTO extends DTO {
+    @Expect(DTO.String().optional().default('world').description('Who is greeted'))
+    public name: string
+}

package/template/src/tests/App.spec.ts

@@ -0,0 +1,33 @@
+import {after, before, describe, it} from 'node:test'
+import assert from 'node:assert'
+import {Application} from 'lakutata'
+import {installerConfig} from '../config/Config.js'
+
+const PORT: number = 18080
+
+describe('{$APP_NAME}', (): void => {
+
+    let app: Application
+
+    before(async (): Promise<void> => {
+        app = await new Promise<Application>((resolve: (app: Application) => void): void => {
+            Application.run(installerConfig(PORT)).onLaunched((launched: Application): void => resolve(launched))
+        })
+    })
+
+    after(async (): Promise<void> => {
+        await app?.dispose()
+    })
+
+    it('greets', async (): Promise<void> => {
+        const response: Response = await fetch(`http://127.0.0.1:${PORT}/example?name=you`)
+        assert.deepStrictEqual(await response.json(), {message: 'Hello, you!'})
+    })
+    //@if i18n
+
+    it('greets in the language of the request', async (): Promise<void> => {
+        const response: Response = await fetch(`http://127.0.0.1:${PORT}/example?name=you`, {headers: {'Accept-Language': 'zh-CN,zh;q=0.9'}})
+        assert.deepStrictEqual(await response.json(), {message: '你好，you！'})
+    })
+    //@end
+})

package/template/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "ESNext.Disposable"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "rootDir": "src",
+    "outDir": "build",
+    "types": ["node"],
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "useDefineForClassFields": false,
+    "strict": true,
+    "strictPropertyInitialization": false,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "sourceMap": true
+  },
+  "include": ["src"]
+}