@platformatic/nest 3.71.1-alpha.0 → 4.0.0-alpha.1

package/index.d.ts

@@ -1,4 +1,4 @@
-import { BaseCapability, BaseContext, BaseOptions } from '@platformatic/basic'
+import { ApplicationDefinition, BaseCapability, BaseContext, BaseOptions, CapabilityFactoryOptions, ConfigContext, DeferredApplicationDefinition } from '@platformatic/basic'
 import { Configuration, ConfigurationOptions } from '@platformatic/foundation'
 import { JSONSchemaType } from 'ajv'
 import type { PlatformaticNestJSConfig } from './config.d.ts'
@@ -36,3 +36,10 @@ export declare const schema: JSONSchemaType<PlatformaticNestJSConfig>
 export declare const schemaComponents: { nest: JSONSchemaType<object> }
 export declare const version: string
 export declare const supportedVersions: string
+
+export type NestConfigOptions = CapabilityFactoryOptions<PlatformaticNestJSConfig, 'nest', never>
+
+export declare function createNestConfig (options?: NestConfigOptions): ApplicationDefinition
+export declare function createNestConfig (
+  callback: (context: ConfigContext) => NestConfigOptions | Promise<NestConfigOptions>
+): DeferredApplicationDefinition

package/index.js

@@ -1,5 +1,5 @@
-import { transform as basicTransform, resolve, validationOptions } from '@platformatic/basic'
-import { kMetadata, loadConfiguration as utilsLoadConfiguration } from '@platformatic/foundation'
+import { loadCapabilityConfiguration, transform as basicTransform, validationOptions } from '@platformatic/basic'
+import { kMetadata } from '@platformatic/foundation'
 import { NestCapability } from './lib/capability.js'
 import { schema } from './lib/schema.js'
 
@@ -11,14 +11,12 @@ export async function transform (config, schema, options) {
 }
 
 export async function loadConfiguration (configOrRoot, sourceOrConfig, context) {
-  const { root, source } = await resolve(configOrRoot, sourceOrConfig, 'application')
-
-  return utilsLoadConfiguration(source, context?.schema ?? schema, {
+  return loadCapabilityConfiguration(configOrRoot, sourceOrConfig, context, {
+    schema,
+    scope: import.meta.filename,
+    suffixes: 'application',
     validationOptions,
-    transform,
-    replaceEnv: true,
-    root,
-    ...context
+    transform
   })
 }
 
@@ -29,3 +27,5 @@ export async function create (configOrRoot, sourceOrConfig, context) {
 
 export * from './lib/capability.js'
 export { packageJson, schema, schemaComponents, version } from './lib/schema.js'
+
+export * from './lib/factory.js'

package/lib/capability.js

@@ -30,6 +30,8 @@ export class NestCapability extends BaseCapability {
   #app
   #server
   #dispatcher
+  #managedDevelopment
+  #originalDevelopmentEnvironment
 
   constructor (root, config, context) {
     super('nest', version, root, config, context)
@@ -56,17 +58,10 @@ export class NestCapability extends BaseCapability {
       : undefined
 
     this.registerGlobals({ basePath: this.#basePath })
-
-    this.subprocessForceClose = true
   }
 
-  async start ({ listen }) {
-    // Make this idempotent
-    if (this.url) {
-      return this.url
-    }
-
-    await super._start({ listen })
+  async _start () {
+    await super._start()
 
     const config = this.config
     const command = config.application.commands[this.isProduction ? 'production' : 'development']
@@ -77,7 +72,19 @@ export class NestCapability extends BaseCapability {
     })
 
     if (command || !this.isProduction) {
-      await this.startWithCommand(command || `node ${this.#nestjsCli} start --watch --preserveWatchOutput`)
+      this.#managedDevelopment = !command && !this.isProduction
+
+      if (this.#managedDevelopment && typeof this.serverConfig?.port === 'undefined') {
+        this.#managedDevelopment = false
+        return
+      }
+
+      try {
+        await this.startWithCommand(command || `node ${this.#nestjsCli} start --watch --preserveWatchOutput`)
+      } finally {
+        this.#restoreDevelopmentEnvironment()
+        this.#managedDevelopment = false
+      }
 
       // We use url changing as a way to notify restarts
       this.childManager.on('url', () => {
@@ -85,12 +92,12 @@ export class NestCapability extends BaseCapability {
         events.emitAndNotify('url', this.url)
       })
     } else {
-      return this.#startProduction(listen)
+      return this.#startProduction()
     }
   }
 
-  async stop () {
-    await super.stop()
+  async _stop () {
+    await super._stop()
 
     if (this.childManager) {
       return this.stopCommand()
@@ -167,15 +174,12 @@ export class NestCapability extends BaseCapability {
   getMeta () {
     const hasBasePath = this.basePath || this.#basePath
 
-    return {
-      gateway: {
-        tcp: typeof this.url !== 'undefined',
-        url: this.url,
-        prefix: this.basePath ?? this.#basePath,
-        wantsAbsoluteUrls: !!hasBasePath,
-        needsRootTrailingSlash: false
-      }
-    }
+    return super.getMeta({
+      includeConnection: true,
+      prefix: this.basePath ?? this.#basePath,
+      wantsAbsoluteUrls: !!hasBasePath,
+      needsRootTrailingSlash: false
+    })
   }
 
   /* c8 ignore next 5 */
@@ -188,22 +192,42 @@ export class NestCapability extends BaseCapability {
   async getChildManagerContext (basePath) {
     const context = await super.getChildManagerContext(basePath)
 
-    // In development mode we need to choose the random port in advance as the Nest CLI will start a new process
-    // every time the code changes and thus we need to ensure that the port is always the same.
-    if (!this.isProduction && (context.port === true || context.port === 0)) {
-      context.port = await getPort()
+    // In managed development mode the Nest CLI starts the application in another process. Choose an ephemeral
+    // port once when needed and pass capability-owned listener settings through the environment inherited by
+    // that process. Applications started with custom commands remain responsible for their own listener.
+    if (this.#managedDevelopment) {
+      if (context.port === true || context.port === 0) {
+        const environmentPort = Number(process.env.PORT)
+        context.port = Number.isInteger(environmentPort) && environmentPort > 0 ? environmentPort : await getPort()
+      }
+
+      this.#originalDevelopmentEnvironment = new Map([
+        ['PORT', process.env.PORT],
+        ['HOST', process.env.HOST]
+      ])
+      process.env.PORT = context.port.toString()
+
+      if (typeof context.host === 'string') {
+        process.env.HOST = context.host
+      }
     }
 
     return context
   }
 
-  async #startProduction (listen) {
-    // Listen if entrypoint
-    if (this.#app && listen) {
-      await this.#listen()
-      return this.url
+  #restoreDevelopmentEnvironment () {
+    for (const [key, value] of this.#originalDevelopmentEnvironment ?? []) {
+      if (typeof value === 'undefined') {
+        delete process.env[key]
+      } else {
+        process.env[key] = value
+      }
     }
 
+    this.#originalDevelopmentEnvironment = null
+  }
+
+  async #startProduction () {
     const outputDirectory = this.config.application.outputDirectory
     const { path, name } = this.config.nest.appModule
     this.verifyOutputDirectory(resolve(this.root, outputDirectory))
@@ -241,23 +265,22 @@ export class NestCapability extends BaseCapability {
       this.#dispatcher = this.#server.listeners('request')[0]
     }
 
-    if (listen) {
-      await this.#listen()
-    }
+    await this.#listen()
 
     await this._collectMetrics()
     return this.url
   }
 
   async #listen () {
+    if (typeof this.serverConfig?.port === 'undefined') {
+      return
+    }
+
     const serverOptions = this.serverConfig
     const listenOptions = buildListenOptions(serverOptions)
+    const serverPromise = createServerListener()
 
-    if (typeof serverOptions?.backlog === 'number') {
-      createServerListener(false, false, { backlog: serverOptions.backlog })
-    }
-
-    await this.#app.listen(listenOptions)
+    await Promise.all([this.#app.listen(listenOptions), serverPromise])
     this.url = getServerUrl(this.#isFastify ? this.#server.server : this.#server)
 
     return this.url

package/lib/factory.js

@@ -0,0 +1,7 @@
+import { defineCapabilityFactory } from '@platformatic/basic'
+import { schema, version } from './schema.js'
+
+export const createNestConfig = defineCapabilityFactory('@platformatic/nest', schema, {
+  version,
+  flatten: ['nest']
+})

package/lib/schema.js

@@ -1,11 +1,14 @@
-import { schemaComponents as basicSchemaComponents } from '@platformatic/basic'
-import { schemaComponents as utilsSchemaComponents } from '@platformatic/foundation'
+import { schemaComponents as basicSchemaComponents } from '@platformatic/basic/schema'
+import { schemaComponents as utilsSchemaComponents } from '@platformatic/foundation/schema'
 import { readFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 
 export const packageJson = JSON.parse(readFileSync(resolve(import.meta.dirname, '../package.json'), 'utf8'))
 export const version = packageJson.version
 
+// Production builds an in-thread application and awaits ready() before the port check.
+export const servesWithoutPort = { development: false, production: true }
+
 const nest = {
   type: 'object',
   properties: {

package/package.json

@@ -1,9 +1,15 @@
 {
   "name": "@platformatic/nest",
-  "version": "3.71.1-alpha.0",
+  "version": "4.0.0-alpha.1",
   "description": "Platformatic Nest.js Capability",
   "main": "index.js",
   "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./schema": "./schema.js",
+    "./package.json": "./package.json",
+    "./*": "./*"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/platformatic/platformatic.git"
@@ -18,10 +24,10 @@
     "get-port": "^7.1.0",
     "light-my-request": "^6.0.0",
     "pino-http": "^10.2.0",
-    "@platformatic/basic": "3.71.1-alpha.0",
-    "@platformatic/foundation": "3.71.1-alpha.0",
-    "@platformatic/generators": "3.71.1-alpha.0",
-    "@platformatic/globals": "3.71.1-alpha.0"
+    "@platformatic/basic": "4.0.0-alpha.1",
+    "@platformatic/foundation": "4.0.0-alpha.1",
+    "@platformatic/generators": "4.0.0-alpha.1",
+    "@platformatic/globals": "4.0.0-alpha.1"
   },
   "devDependencies": {
     "@nestjs/cli": "^11.0.7",
@@ -35,11 +41,11 @@
     "tstyche": "^7.0.0",
     "tsx": "^4.19.0",
     "typescript": "~6.0.3",
-    "@platformatic/gateway": "3.71.1-alpha.0",
-    "@platformatic/service": "3.71.1-alpha.0"
+    "@platformatic/gateway": "4.0.0-alpha.1",
+    "@platformatic/service": "4.0.0-alpha.1"
   },
   "engines": {
-    "node": ">=22.19.0"
+    "node": ">=24.20.0"
   },
   "scripts": {
     "test": "npm run test:types && node --test --test-reporter=cleaner-spec-reporter --test-concurrency=1 --test-timeout=2000000 test/*.test.js test/**/*.test.js",

package/schema.js

@@ -0,0 +1,7 @@
+// The light /schema subpath, part of the capability contract. It carries the schema and the
+// package-level metadata main-side preparation needs, and imports nothing that would pull the
+// capability's implementation in with it — boot resolves this rather than the package entry.
+//
+// Light is a statement about import cost, never about safety: this executes in the main process
+// with full privileges, like any capability code.
+export * from './lib/schema.js'