@starci/hfs 5.0.7 → 5.1.0

package/templates/be/skeleton-lite/src/modules/integrations/passport/strategies/local.strategy.ts

@@ -1,4 +1,5 @@
 import { Injectable } from "@nestjs/common"
+import type { Type } from "@nestjs/common"
 import { PassportStrategy } from "@nestjs/passport"
 import { Strategy } from "passport-local"
 import { PassportError, PassportErrorCode } from "../errors/passport.error"
@@ -18,9 +19,12 @@ export interface PasswordAccount {
 /** The lookup the identity domain provides: the account of one email, or undefined. */
 export type FindPasswordAccount = (email: string) => Promise<PasswordAccount | undefined>
 
+/** The Passport strategy base of the local scheme, typed as the class the strategy extends. */
+const LocalStrategyBase: Type<object> = PassportStrategy(Strategy, "local")
+
 @Injectable()
 /** Email and password sign-in: bcrypt against the stored hash; a miss and a wrong password fail alike. */
-export class LocalStrategy extends PassportStrategy(Strategy, "local") {
+export class LocalStrategy extends LocalStrategyBase {
     constructor(@InjectPasswordAccounts() private readonly findAccount: FindPasswordAccount) {
         super({ usernameField: "email", passwordField: "password" })
     }

package/templates/be/skeleton-lite/src/modules/platform/database/database.port.ts

@@ -5,7 +5,7 @@ import type { DatabaseOptions } from "./database.options"
 import { PRIMARY_CONNECTION } from "./primary.connection"
 
 /** The primary pool's override token for infrastructure fixtures; TypeORM tokens stay owned by this capability. */
-export const PRIMARY_DATA_SOURCE = getDataSourceToken(PRIMARY_CONNECTION)
+export const PRIMARY_DATA_SOURCE: ReturnType<typeof getDataSourceToken> = getDataSourceToken(PRIMARY_CONNECTION)
 
 /** Token of the options of the database capability. */
 export const DATABASE_OPTIONS: unique symbol = Symbol("platform.database.options")

package/templates/be/skeleton-lite/src/modules/platform/http-security/persistence/entities/index.ts

@@ -1,4 +1,4 @@
 import { RateWindowEntity } from "./rate-window.entity"
 
 /** The entities of the http-security capability, named in PRIMARY_ENTITIES of platform/database/entities.ts. */
-export const httpSecurityEntities = [RateWindowEntity]
+export const httpSecurityEntities: ReadonlyArray<typeof RateWindowEntity> = [RateWindowEntity]

package/templates/be/skeleton-lite/src/tests/fixtures/builders/api.builder.ts

@@ -4,8 +4,14 @@ import { ACCESS_TOKEN_VERIFIER } from "@modules/domain/identity"
 import { OWN_TOKEN_VERIFIER } from "@modules/integrations/passport"
 import { OBJECT_STORAGE } from "@modules/integrations/object-storage"
 
+/** What a wiring proof hands the compiled root: public options and the infrastructure doubles. */
+export interface WiringProof {
+    readonly options: Readonly<Record<string, unknown>>
+    readonly overrides: ReadonlyArray<{ readonly token: unknown; readonly value: unknown }>
+}
+
 /** Compiles the real API root with public configuration and explicit infrastructure doubles. */
-export const buildWiringProof = () => ({
+export const buildWiringProof = (): WiringProof => ({
     options: {
         server: { port: 3000 },
         httpSecurity: {

package/templates/be/skeleton-lite/src/tests/fixtures/builders/cli.builder.ts

@@ -2,8 +2,14 @@ import { getDataSourceToken } from "@nestjs/typeorm"
 import { Secret } from "@modules/platform/config"
 import { PRIMARY_CONNECTION } from "@modules/platform/database"
 
+/** What a wiring proof hands the compiled root: public options and the infrastructure doubles. */
+export interface WiringProof {
+    readonly options: Readonly<Record<string, unknown>>
+    readonly overrides: ReadonlyArray<{ readonly token: unknown; readonly value: unknown }>
+}
+
 /** Public fixture options and the database double for compiling the real CLI AppModule without network access. */
-export const buildWiringProof = () => ({
+export const buildWiringProof = (): WiringProof => ({
     options: {
         connections: [{
             name: PRIMARY_CONNECTION,

package/templates/be/table/api/feature.module-definition.ts.tpl

@@ -1,6 +1,12 @@
-import { ConfigurableModuleBuilder } from "@nestjs/common"
+import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
 import type { {{Name}}ApiOptions } from "./{{name}}.options"
 
+const built = new ConfigurableModuleBuilder<{{Name}}ApiOptions>().setClassMethodName("register").build()
+type Host = ConfigurableModuleHost<{{Name}}ApiOptions, "register", "create", {}>
+
 /** The configurable-module base of the {{name}} module. */
-export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
-    new ConfigurableModuleBuilder<{{Name}}ApiOptions>().setClassMethodName("register").build()
+export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
+/** The injection token of the registered options. */
+export const MODULE_OPTIONS_TOKEN: Host["MODULE_OPTIONS_TOKEN"] = built.MODULE_OPTIONS_TOKEN
+/** The options of a synchronous registration, for the register signature. */
+export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE

package/templates/be/table/api/graphql.module-definition.ts.tpl

@@ -1,6 +1,12 @@
-import { ConfigurableModuleBuilder } from "@nestjs/common"
+import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
 import type { {{Name}}GraphqlOptions } from "./{{name}}-graphql.options"
 
+const built = new ConfigurableModuleBuilder<{{Name}}GraphqlOptions>().setClassMethodName("register").build()
+type Host = ConfigurableModuleHost<{{Name}}GraphqlOptions, "register", "create", {}>
+
 /** The configurable-module base of the {{name}}-graphql module. */
-export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
-    new ConfigurableModuleBuilder<{{Name}}GraphqlOptions>().setClassMethodName("register").build()
+export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
+/** The injection token of the registered options. */
+export const MODULE_OPTIONS_TOKEN: Host["MODULE_OPTIONS_TOKEN"] = built.MODULE_OPTIONS_TOKEN
+/** The options of a synchronous registration, for the register signature. */
+export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE

package/templates/be/table/entities.index.ts.tpl

@@ -1,4 +1,4 @@
 import { {{Singular}}Entity } from "./{{name}}.entity"
 
 /** The entities of the {{name}} capability, named in PRIMARY_ENTITIES of platform/database/entities.ts. */
-export const {{nameCamel}}Entities = [{{Singular}}Entity]
+export const {{nameCamel}}Entities: ReadonlyArray<typeof {{Singular}}Entity> = [{{Singular}}Entity]

package/templates/be/table/module-definition.ts.tpl

@@ -1,7 +1,12 @@
-import { ConfigurableModuleBuilder } from "@nestjs/common"
+import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
 import type { {{Name}}Options } from "./{{name}}.options"
 
-/** The configurable-module base of the {{name}} capability. */
-export const { ConfigurableModuleClass, OPTIONS_TYPE } = new ConfigurableModuleBuilder<{{Name}}Options>()
+const built = new ConfigurableModuleBuilder<{{Name}}Options>()
     .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
     .build()
+type Host = ConfigurableModuleHost<{{Name}}Options, "register", "create", { isGlobal: boolean }>
+
+/** The configurable-module base of the {{name}} capability. */
+export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
+/** The options of a synchronous registration, for the register signature. */
+export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE

package/templates/be/test-world/fixtures/migrations.sql.ts.tpl

@@ -1,5 +1,6 @@
 import type { EntityManager } from "typeorm"
 import { sql } from "@modules/platform/database"
+import type { SqlText } from "@modules/platform/database"
 
 /** One row of a connection's migration ledger: the name of a migration the cli migrate step applied. */
 export interface AppliedMigrationRow {

package/templates/be/test-world/world/test-world.config.ts.tpl

@@ -5,10 +5,11 @@
  */
 import { applyCorrelation } from "@modules/platform/logging"
 import { defineTestWorld } from "@starci/test-world"
+import type { TestWorldApi } from "@starci/test-world"
 {{appModuleImports}}
 import { {{optionsImports}} } from "./test-apps.options"
 
-export const { useTestWorld, useSandbox } = defineTestWorld({
+const world: TestWorldApi = defineTestWorld({
     stack: ".starcistacks/dev",
     stacks: {
         postgresql: { connections: [{{connectionDeclarations}}] },
@@ -19,3 +20,9 @@ export const { useTestWorld, useSandbox } = defineTestWorld({
     migrate: { module: migrateCli, options: cliOptionsOf },
     modules: { base: platformBase },
 })
+
+/** Registers the hooks that boot and close the world around a spec and answers its handle; call it inside `describe`. */
+export const useTestWorld: TestWorldApi["useTestWorld"] = world.useTestWorld
+
+/** The contract layer: the real integration client against a provider sandbox, in a `contract-spec`. */
+export const useSandbox: TestWorldApi["useSandbox"] = world.useSandbox

package/templates/fe/common/app-layout.tsx.partial

@@ -1,4 +1,4 @@
-export const AppLayout = async (props: AppLayoutProps) => {
+export const AppLayout = async (props: AppLayoutProps): Promise<ReactElement> => {
     const t = await getTranslations("app.shell")
     return (
         <SiteShell brand={t("brand")} homeHref={APP_ROUTES.home}>

package/templates/fe/skeleton/apps/__app__/src/hooks/auth/useSession.ts

@@ -2,9 +2,10 @@
 
 import { useDebugValue } from "react"
 import { useAppSelector } from "@/redux"
+import type { SessionState } from "@/redux"
 
 /** The reader's session as the app shares it (redux, kept by the auth session effect): unknown, signed in or signed out. */
-export const useSession = () => {
+export const useSession = (): SessionState => {
     const session = useAppSelector((state) => state.session)
     useDebugValue(session.status)
     return session

package/templates/fe/skeleton/apps/__app__/src/hooks/auth/useSignIn.ts

@@ -12,18 +12,26 @@ const FAILURES: readonly SignInFailure[] = ["refused", "invalid", "unavailable"]
 /** The failure of a sign-in's failure kind. */
 const failureOf = (kind: string): SignInFailure => FAILURES.find((each) => each === kind) ?? "unavailable"
 
+/** What the sign-in hook answers: whether a request runs, why the last one failed, the sign-in itself and `reject`. */
+export interface SignIn {
+    readonly failure: SignInFailure | undefined
+    readonly pending: boolean
+    readonly signIn: (email: string, password: string) => void
+    readonly reject: () => void
+}
+
 /**
  * Signs the reader in with an email and a password through modules/auth: whether a request runs, why the last one failed,
  * the sign-in itself and `reject` for input the form could not read. A success needs no state here: the session effect
  * moves the reader to signed in.
  */
-export const useSignIn = () => {
+export const useSignIn = (): SignIn => {
     const [failure, setFailure] = useState<SignInFailure>()
     const [pending, startTransition] = useTransition()
-    const signIn = (email: string, password: string) =>
+    const signIn = (email: string, password: string): void =>
         startTransition(async () => {
             const failed = await authClient.signInWithPassword(email, password)
             setFailure(failed === undefined ? undefined : failureOf(failed.kind))
         })
-    return { failure, pending, signIn, reject: () => setFailure("invalid") }
+    return { failure, pending, signIn, reject: (): void => setFailure("invalid") }
 }

package/templates/fe/skeleton/apps/__app__/src/hooks/auth/useSignOut.ts

@@ -11,14 +11,20 @@ const responseOf = (failure: AuthFailure | undefined) =>
         ? { success: true as const, data: null }
         : { success: false as const, error: failure.code, kind: failure.kind, message: failure.message }
 
+/** What the sign-out hook answers: whether the request runs and the sign-out itself. */
+export interface SignOut {
+    readonly pending: boolean
+    readonly signOut: () => void
+}
+
 /**
  * Ends the reader's session through modules/auth: whether the request runs and the sign-out itself. A failure is reported by
  * modules/toast; a success needs no toast, the session effect moves the reader to signed out.
  */
-export const useSignOut = () => {
+export const useSignOut = (): SignOut => {
     const withToast = useGraphQLWithToast()
     const [pending, startTransition] = useTransition()
-    const signOut = () =>
+    const signOut = (): void =>
         startTransition(async () => {
             await withToast(async () => responseOf(await authClient.signOut()), { showSuccessToast: false })
         })

package/templates/fe/skeleton/apps/__app__/src/hooks/zustand/appGuide/store.ts

@@ -1,6 +1,7 @@
 "use client"
 
 import { create } from "zustand"
+import type { StoreApi, UseBoundStore } from "zustand"
 
 /** The home guide's local UI state; it carries no session or server data. */
 type AppGuideState = {
@@ -9,7 +10,7 @@ type AppGuideState = {
 }
 
 /** One feature-local store, shared by the guide trigger and its controlled dialog. */
-export const useAppGuideStore = create<AppGuideState>()((set) => ({
+export const useAppGuideStore: UseBoundStore<StoreApi<AppGuideState>> = create<AppGuideState>()((set) => ({
     isOpen: false,
     setOpen: (isOpen) => set({ isOpen }),
 }))

package/templates/fe/skeleton/apps/__app__/src/modules/toast/hooks.ts

@@ -23,7 +23,7 @@ const useToastMessages = (): ToastMessages => {
 }
 
 /** A localized runGraphQLWithToast: every GraphQL write reports its outcome through it. */
-export const useGraphQLWithToast = () => {
+export const useGraphQLWithToast = (): (<T>(action: () => Promise<GraphQLResponse<T>>, options?: RunWithToastOptions) => Promise<GraphQLResponse<T>>) => {
     const messages = useToastMessages()
     return useCallback(
         <T>(action: () => Promise<GraphQLResponse<T>>, options?: RunWithToastOptions) =>

package/templates/fe/skeleton/apps/__app__/src/modules/toast/toast.tsx

@@ -18,8 +18,11 @@ const INDICATOR: Record<"success" | "danger" | "warning" | "info", ReactNode> =
     info: <InformationCircleIcon className="size-6" />,
 }
 
+/** The app's toast: HeroUI's, with the four status methods wrapped. */
+type AppToast = typeof heroToast
+
 /** The app's toast: HeroUI's imperative toast with the status indicator injected; the region is mounted by the providers. */
-export const toast = {
+export const toast: AppToast = {
     ...heroToast,
     success: (message: ReactNode, options?: StatusToastOptions) =>
         heroToast.success(message, { indicator: INDICATOR.success, ...options }),

package/templates/fe/skeleton/apps/__app__/src/redux/hooks.ts

@@ -1,8 +1,9 @@
 import { useDispatch, useSelector } from "react-redux"
+import type { UseDispatch, UseSelector } from "react-redux"
 import type { AppDispatch, RootState } from "./store"
 
 /** The typed dispatch of the app's store. */
-export const useAppDispatch = useDispatch.withTypes<AppDispatch>()
+export const useAppDispatch: UseDispatch<AppDispatch> = useDispatch.withTypes<AppDispatch>()
 
 /** The typed selector of the app's store. */
-export const useAppSelector = useSelector.withTypes<RootState>()
+export const useAppSelector: UseSelector<RootState> = useSelector.withTypes<RootState>()

package/templates/fe/skeleton/apps/__app__/src/redux/index.ts

@@ -1,3 +1,4 @@
 export { useAppDispatch, useAppSelector } from "./hooks"
 export { ReduxProvider } from "./ReduxProvider"
 export { sessionChanged } from "./slices/session"
+export type { SessionState } from "./slices/session"

package/templates/fe/skeleton/apps/__app__/src/redux/slices/session.ts

@@ -1,5 +1,5 @@
 import { createSlice } from "@reduxjs/toolkit"
-import type { PayloadAction } from "@reduxjs/toolkit"
+import type { CaseReducer, PayloadAction, Reducer, Slice } from "@reduxjs/toolkit"
 import type { AuthSession } from "@/modules/auth"
 
 /** The reader's session as the app shares it: unknown until modules/auth answers, then signed in or signed out. */
@@ -8,10 +8,18 @@ export interface SessionState {
     readonly session?: AuthSession
 }
 
+/** The reducers of the session slice. */
+interface SessionReducers {
+    sessionChanged: CaseReducer<SessionState, PayloadAction<AuthSession | undefined>>
+}
+
+/** The session slice as the store and the effects see it. */
+type SessionSlice = Slice<SessionState, SessionReducers, "session">
+
 const initialState: SessionState = { status: "unknown" }
 
 /** The session slice: written only by the auth session effect (hooks/effects), read by any component through useAppSelector. */
-export const sessionSlice = createSlice({
+export const sessionSlice: SessionSlice = createSlice({
     name: "session",
     initialState,
     reducers: {
@@ -21,6 +29,6 @@ export const sessionSlice = createSlice({
 })
 
 /** The one action of the session slice: modules/auth reported a session (or none). */
-export const { sessionChanged } = sessionSlice.actions
+export const sessionChanged: SessionSlice["actions"]["sessionChanged"] = sessionSlice.actions.sessionChanged
 /** The reducer the store mounts under `session`. */
-export const sessionReducer = sessionSlice.reducer
+export const sessionReducer: Reducer<SessionState> = sessionSlice.reducer

package/templates/fe/skeleton/apps/__app__/src/redux/store.ts

@@ -1,14 +1,19 @@
 import { configureStore } from "@reduxjs/toolkit"
+import type { EnhancedStore } from "@reduxjs/toolkit"
 import { sessionReducer } from "./slices/session"
+import type { SessionState } from "./slices/session"
+
+/** The state of the store, for useAppSelector: one slice per key of the root reducer. */
+export interface RootState {
+    readonly session: SessionState
+}
 
 /** The one store of the app: app-wide shared state only (feature-local state lives in hooks/zustand). */
-export const store = configureStore({
+export const store: EnhancedStore<RootState> = configureStore({
     reducer: {
         session: sessionReducer,
     },
 })
 
-/** The state of the store, for useAppSelector. */
-export type RootState = ReturnType<typeof store.getState>
 /** The dispatch of the store, for useAppDispatch. */
 export type AppDispatch = typeof store.dispatch

package/templates/fe/skeleton/apps/app/src/app/[locale]/layout.tsx

@@ -1,4 +1,5 @@
-import type { ReactNode } from "react"
+import type { Metadata } from "next"
+import type { ReactElement, ReactNode } from "react"
 import { LocaleShell } from "@{{project}}/ui"
 import { AppProviders } from "@/components/providers/AppProviders"
 import { AppLayout, appLayoutMetadata } from "@/features/layouts/AppLayout"
@@ -11,10 +12,10 @@ type LayoutProps = {
 }
 
 /** The localized document title of this route segment. */
-export const generateMetadata = async (props: LayoutProps) => appLayoutMetadata((await props.params).locale)
+export const generateMetadata = async (props: LayoutProps): Promise<Metadata> => appLayoutMetadata((await props.params).locale)
 
 /** The locale segment's layout slot: the document of the address's language, the app's client providers and its chrome. */
-const Layout = async (props: LayoutProps) => (
+const Layout = async (props: LayoutProps): Promise<ReactElement> => (
     <LocaleShell
         {...await appI18n.readLocaleSegment(props.params)}
         content={

package/templates/fe/skeleton/apps/app/src/features/layouts/AppLayout/index.tsx

@@ -1,6 +1,6 @@
 import type { Metadata } from "next"
 import { getTranslations } from "next-intl/server"
-import type { ReactNode } from "react"
+import type { ReactElement, ReactNode } from "react"
 import { SiteShell } from "@{{project}}/ui"
 import { siteUrl } from "@/modules/config"
 import { APP_ROUTES } from "@/modules/routes"

package/templates/fe/skeleton/apps/app/src/features/pages/AppHomePage/index.tsx

@@ -1,3 +1,4 @@
+import type { ReactElement } from "react"
 import type { Metadata } from "next"
 import { getTranslations } from "next-intl/server"
 import { AppGuideOverlay } from "@/features/overlays/AppGuideOverlay"
@@ -10,7 +11,7 @@ export const appHomeMetadata = async (): Promise<Metadata> => {
 }
 
 /** The first page of the product app: a server component; the session surface it draws runs on the client. */
-export const AppHomePage = async () => {
+export const AppHomePage = async (): Promise<ReactElement> => {
     const t = await getTranslations("app.home")
     return (
         <>

package/templates/fe/skeleton/apps/app/src/features/pages/AppLoadingPage/index.tsx

@@ -1,8 +1,9 @@
+import type { ReactElement } from "react"
 import { getTranslations } from "next-intl/server"
 import { LoadingNotice } from "@{{project}}/ui"
 
 /** Shown while a route of the product app resolves. */
-export const AppLoadingPage = async () => {
+export const AppLoadingPage = async (): Promise<ReactElement> => {
     const t = await getTranslations("app.loading")
     return <LoadingNotice label={t("message")} />
 }

package/templates/fe/skeleton/apps/app/src/features/pages/AppNotFoundPage/index.tsx

@@ -1,9 +1,10 @@
+import type { ReactElement } from "react"
 import { getTranslations } from "next-intl/server"
 import { NotFoundNotice } from "@{{project}}/ui"
 import { APP_ROUTES } from "@/modules/routes"
 
 /** Shown when a route of the product app calls `notFound()`. */
-export const AppNotFoundPage = async () => {
+export const AppNotFoundPage = async (): Promise<ReactElement> => {
     const t = await getTranslations("app.notFound")
     return <NotFoundNotice title={t("title")} homeLabel={t("home")} homeHref={APP_ROUTES.home} />
 }

package/templates/fe/skeleton/apps/app/src/modules/i18n/index.ts

@@ -1,4 +1,5 @@
 import { createAppI18n } from "@{{project}}/i18n"
+import type { AppI18n } from "@{{project}}/i18n"
 
 /** The product app's i18n: the product's one next-intl stack (the i18n package), with this app's own catalogs under `messages/`. */
-export const appI18n = createAppI18n("app", (locale) => import(`./messages/${locale}.json`))
+export const appI18n: AppI18n = createAppI18n("app", (locale) => import(`./messages/${locale}.json`))

package/templates/fe/skeleton/apps/app/src/modules/i18n/request.ts

@@ -1,4 +1,7 @@
 import { appI18n } from "./index"
+import type { AppI18n } from "@{{project}}/i18n"
 
 /** The request config next-intl's plugin loads (next.config.ts): the product stack over this app's catalogs. */
-export default appI18n.requestConfig
+const requestConfig: AppI18n["requestConfig"] = appI18n.requestConfig
+
+export default requestConfig

package/templates/fe/skeleton/apps/landing/src/app/[locale]/layout.tsx

@@ -1,4 +1,5 @@
-import type { ReactNode } from "react"
+import type { Metadata } from "next"
+import type { ReactElement, ReactNode } from "react"
 import { LocaleShell } from "@{{project}}/ui"
 import { LandingLayout, landingLayoutMetadata } from "@/features/layouts/LandingLayout"
 import { landingI18n } from "@/modules/i18n"
@@ -10,10 +11,10 @@ type LayoutProps = {
 }
 
 /** The localized document title and description of the landing. */
-export const generateMetadata = async (props: LayoutProps) => landingLayoutMetadata((await props.params).locale)
+export const generateMetadata = async (props: LayoutProps): Promise<Metadata> => landingLayoutMetadata((await props.params).locale)
 
 /** The locale segment's layout slot: the document of the address's language around the landing's chrome. */
-const Layout = async (props: LayoutProps) => (
+const Layout = async (props: LayoutProps): Promise<ReactElement> => (
     <LocaleShell {...await landingI18n.readLocaleSegment(props.params)} content={<LandingLayout content={props.children} />} />
 )
 

package/templates/fe/skeleton/apps/landing/src/features/layouts/LandingLayout/index.tsx

@@ -1,6 +1,6 @@
 import type { Metadata } from "next"
 import { getTranslations } from "next-intl/server"
-import type { ReactNode } from "react"
+import type { ReactElement, ReactNode } from "react"
 import { SiteShell } from "@{{project}}/ui"
 import { LANDING_ROUTES } from "@/modules/routes"
 
@@ -14,7 +14,7 @@ export const landingLayoutMetadata = async (locale: string): Promise<Metadata> =
 }
 
 /** The landing's chrome, resolved on the server: the shared brand shell with the wordmark linking home, around the routed body. */
-export const LandingLayout = async (props: LandingLayoutProps) => {
+export const LandingLayout = async (props: LandingLayoutProps): Promise<ReactElement> => {
     const t = await getTranslations("landing.shell")
     return (
         <SiteShell brand={t("brand")} homeHref={LANDING_ROUTES.home}>

package/templates/fe/skeleton/apps/landing/src/features/pages/LandingLoadingPage/index.tsx

@@ -1,8 +1,9 @@
+import type { ReactElement } from "react"
 import { getTranslations } from "next-intl/server"
 import { LoadingNotice } from "@{{project}}/ui"
 
 /** Shown while a route of the landing resolves. */
-export const LandingLoadingPage = async () => {
+export const LandingLoadingPage = async (): Promise<ReactElement> => {
     const t = await getTranslations("landing.loading")
     return <LoadingNotice label={t("message")} />
 }

package/templates/fe/skeleton/apps/landing/src/features/pages/LandingNotFoundPage/index.tsx

@@ -1,9 +1,10 @@
+import type { ReactElement } from "react"
 import { getTranslations } from "next-intl/server"
 import { NotFoundNotice } from "@{{project}}/ui"
 import { LANDING_ROUTES } from "@/modules/routes"
 
 /** Shown when a route of the landing calls `notFound()`. */
-export const LandingNotFoundPage = async () => {
+export const LandingNotFoundPage = async (): Promise<ReactElement> => {
     const t = await getTranslations("landing.notFound")
     return <NotFoundNotice title={t("title")} homeLabel={t("home")} homeHref={LANDING_ROUTES.home} />
 }

package/templates/fe/skeleton/apps/landing/src/features/pages/LandingPage/index.tsx

@@ -1,3 +1,4 @@
+import type { ReactElement } from "react"
 import type { Metadata } from "next"
 import { getTranslations } from "next-intl/server"
 import { appUrl } from "@/modules/config"
@@ -10,7 +11,7 @@ export const landingMetadata = async (): Promise<Metadata> => {
 }
 
 /** The landing page, resolved on the server: its copy from the catalog and the product app's origin from the config module. */
-export const LandingPage = async () => {
+export const LandingPage = async (): Promise<ReactElement> => {
     const t = await getTranslations("landing.home")
     return <LandingPageBase props={{ title: t("title"), lede: t("lede"), openApp: t("openApp"), appHref: appUrl() }} />
 }

package/templates/fe/skeleton/apps/landing/src/modules/i18n/index.ts

@@ -1,4 +1,5 @@
 import { createAppI18n } from "@{{project}}/i18n"
+import type { AppI18n } from "@{{project}}/i18n"
 
 /** The landing's i18n: the product's one next-intl stack (the i18n package), with this app's own catalogs under `messages/`. */
-export const landingI18n = createAppI18n("landing", (locale) => import(`./messages/${locale}.json`))
+export const landingI18n: AppI18n = createAppI18n("landing", (locale) => import(`./messages/${locale}.json`))

package/templates/fe/skeleton/apps/landing/src/modules/i18n/request.ts

@@ -1,4 +1,7 @@
 import { landingI18n } from "./index"
+import type { AppI18n } from "@{{project}}/i18n"
 
 /** The request config next-intl's plugin loads (next.config.ts): the product stack over the landing's catalogs. */
-export default landingI18n.requestConfig
+const requestConfig: AppI18n["requestConfig"] = landingI18n.requestConfig
+
+export default requestConfig

package/templates/fe/skeleton/packages/__project__-i18n/src/index.ts

@@ -6,6 +6,7 @@ import { getMessages, getRequestConfig } from "next-intl/server"
 import { notFound } from "next/navigation"
 import { locale as routeLocale } from "next/root-params"
 import { PRODUCT_TIME_ZONE, routing } from "./routing"
+import type { ProductRouting } from "./routing"
 
 /** Loads one app's own catalog for a served locale. */
 type LoadMessages = (locale: string) => Promise<unknown>
@@ -27,6 +28,23 @@ const isLocaleReader = (value: unknown): value is () => Promise<unknown> => type
 
 const readRouteLocale = async (): Promise<unknown> => (isLocaleReader(routeLocale) ? routeLocale() : undefined)
 
+/** The language the address states, its catalog and the product time zone. */
+interface LocaleSegment {
+    readonly locale: string
+    readonly messages: AbstractIntlMessages
+    readonly timeZone: string
+}
+
+/** The navigation helpers of the product's routing (links, redirects, the locale-aware router). */
+type ProductNavigation = ReturnType<typeof createNavigation<ProductRouting["locales"], "as-needed">>
+
+/** What one app of the product reads of its next-intl stack. */
+export interface AppI18n {
+    readonly navigation: ProductNavigation
+    readonly requestConfig: ReturnType<typeof getRequestConfig>
+    readonly readLocaleSegment: (params: Promise<{ readonly locale: string }>) => Promise<LocaleSegment>
+}
+
 /**
  * The next-intl stack of one app of the product, written once here and called once by each app's `modules/i18n` (R59): the
  * product's one routing with its locale-aware navigation, the request config next-intl's plugin loads (the app's
@@ -34,7 +52,7 @@ const readRouteLocale = async (): Promise<unknown> => (isLocaleReader(routeLocal
  * the app in the text of a message its catalog lacks (`<app>:<namespace>.<key>`); `loadMessages` loads its own catalogs. A server
  * module: a client component reads the default locale from `./routing`.
  */
-export const createAppI18n = (app: string, loadMessages: LoadMessages) => ({
+export const createAppI18n = (app: string, loadMessages: LoadMessages): AppI18n => ({
     navigation: createNavigation(routing),
     /**
      * The locale is the `[locale]` route param read through `next/root-params` (`experimental.rootParams` in the app's next.config.ts,

package/templates/fe/skeleton/packages/__project__-i18n/src/proxy.ts

@@ -20,5 +20,5 @@ const negotiate = createMiddleware(routing)
  * the default and serves the default locale (vi) without a prefix. One routing table for every app; each app's `src/proxy.ts`
  * re-exports this.
  */
-export const proxy = (request: NextRequest) =>
+export const proxy = (request: NextRequest): NextResponse =>
     isUnnegotiated(request.nextUrl.pathname) ? NextResponse.next() : negotiate(request)

package/templates/fe/skeleton/packages/__project__-i18n/src/routing.ts

@@ -1,4 +1,5 @@
 import { defineRouting } from "next-intl/routing"
+import type { RoutingConfig } from "next-intl/routing"
 
 /** The locales every app of the product serves; every catalog of an app has the same keys in each. */
 const LOCALES = ["vi", "en"] as const
@@ -9,11 +10,14 @@ export const DEFAULT_LOCALE = "vi"
 /** The product's time zone: fixed, not inferred, so the server and the hydrated client format the same instant the same way. */
 export const PRODUCT_TIME_ZONE = "Asia/Ho_Chi_Minh"
 
+/** The type of the product's routing table: the served locales, no locale prefix for the default one, no localized pathnames or domains. */
+export type ProductRouting = RoutingConfig<typeof LOCALES, "as-needed", never, never>
+
 /**
  * The one routing table of the product, for the proxy, the navigation and the request config of every app: vi default, a prefix
  * only when the locale is not the default, so `/vi` means the same thing on every app.
  */
-export const routing = defineRouting({
+export const routing: ProductRouting = defineRouting({
     locales: LOCALES,
     defaultLocale: DEFAULT_LOCALE,
     localePrefix: "as-needed",