sleepy-serv 0.7.0 → 0.8.0

package/README.md

@@ -26,9 +26,25 @@ The parameter for `import.meta.dirname` can be any directory you prefer, but it'
 
 ### Return Value
 
-`sleepy-serv` was originally built for NodeJS, but it was ported to `bun` recently (before the initial release). The `createApp()` function merely calls `Bun.serve()` under-the-hood, and returns the `app` object that contains two properties:
+`sleepy-serv` was originally built for NodeJS, but it was ported to `bun` recently (before the initial release). The `createApp()` function merely calls `Bun.serve()` under-the-hood, and returns the `app` object that contains these properties:
 - `routes`: Contains a list of all of the routes defined by the file structure. This is useful for debugging.
-- `server`: this is the object that's returned from `Bun.serve()`. The `server` object has an `async` `.stop()` method on it, which can also be used for graceful shutdowns.
+- `server`: this is the object that's returned from `Bun.serve()`. The `server` object has an `async` `.stop()` method on it, but prefer `app.close()` (see [Shutting Down](#shutting-down)), which stops the server and releases everything else the app holds.
+- `commands`: WebSocket helpers for pushing messages out to connected clients: `send(clientId, event, body)` and `broadcast(event, body)`.
+- `close`: an `async` function that shuts the app down. See [Shutting Down](#shutting-down).
+
+### Shutting Down
+
+`app.close()` shuts the app down and releases everything it holds:
+
+```js
+const app = await createApp(PORT, import.meta.dirname)
+
+await app.close()
+```
+
+It stops the server, tears down the Ctrl+D shutdown handler, and calls [`onClose`](#onclose). Pass `close(true)` to force-close active connections rather than waiting for in-flight requests to finish. That argument is handed straight to `server.stop()`, so it behaves exactly as it does in `Bun.serve()`.
+
+This matters most for tests that start and stop an app per case. Calling `server.stop()` on its own stops the HTTP listener but leaves the Ctrl+D shutdown handler attached to `stdin`, which holds an open handle and can keep the process from exiting. `app.close()` does not have that problem.
 
 ### Adding Routes
 
@@ -465,7 +481,7 @@ Yields these routes:
 
 ### `onClose`
 
-When the app is started, the app can be shutdown gracefully by pressing Ctrl+D in the terminal. The `onClose` hook will be called during that shutdown if it's defined. `onClose` can also be `async` as well.
+When the app is started, the app can be shutdown gracefully by pressing Ctrl+D in the terminal. That handler is only wired up when `stdin` is a TTY, so it's skipped in CI, in test runners, and anywhere `stdin` is piped. The `onClose` hook will be called during that shutdown if it's defined, and it's also called by [`app.close()`](#shutting-down). `onClose` can also be `async` as well.
 
 ```js
 const app = await createApp(PORT, import.meta.dirname, {

package/dist/index.d.ts

@@ -7,10 +7,12 @@ export type { AppOptions, EndpointRequest, FormattedError, Middleware, NextFn, R
 export type { FormatterField, FormatterSchema, ValidationSchemas, } from './middleware';
 export type { SocketCommands } from './socket';
 type OutputRoutes = Record<string, string[]>;
+type CloseFn = (force?: boolean) => Promise<void>;
 export type App = {
     server: Server;
     commands: SocketCommands;
     routes: OutputRoutes;
+    close: CloseFn;
 };
 export declare function createApp(port: number, rootPath: string, opts?: AppOptions): Promise<App>;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAIV,UAAU,EACV,MAAM,EACP,MAAM,SAAS,CAAA;AAEhB,OAAO,KAAK,EAGV,cAAc,EACf,MAAM,UAAU,CAAA;AAEjB,cAAc,UAAU,CAAA;AAExB,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,eAAe,GAChB,MAAM,cAAc,CAAA;AAErB,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAEhD,YAAY,EACV,UAAU,EACV,eAAe,EACf,cAAc,EACd,UAAU,EACV,MAAM,EACN,OAAO,EACP,MAAM,EACN,aAAa,EACb,gBAAgB,GACjB,MAAM,SAAS,CAAA;AAEhB,YAAY,EACV,cAAc,EACd,eAAe,EACf,iBAAiB,GAClB,MAAM,cAAc,CAAA;AAErB,YAAY,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAE9C,KAAK,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;AA4C5C,MAAM,MAAM,GAAG,GAAG;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,cAAc,CAAA;IACxB,MAAM,EAAE,YAAY,CAAA;CACrB,CAAA;AA6YD,wBAAsB,SAAS,CAC7B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,UAAe,GACpB,OAAO,CAAC,GAAG,CAAC,CAad"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAIV,UAAU,EACV,MAAM,EACP,MAAM,SAAS,CAAA;AAEhB,OAAO,KAAK,EAGV,cAAc,EACf,MAAM,UAAU,CAAA;AAEjB,cAAc,UAAU,CAAA;AAExB,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,eAAe,GAChB,MAAM,cAAc,CAAA;AAErB,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAEhD,YAAY,EACV,UAAU,EACV,eAAe,EACf,cAAc,EACd,UAAU,EACV,MAAM,EACN,OAAO,EACP,MAAM,EACN,aAAa,EACb,gBAAgB,GACjB,MAAM,SAAS,CAAA;AAEhB,YAAY,EACV,cAAc,EACd,eAAe,EACf,iBAAiB,GAClB,MAAM,cAAc,CAAA;AAErB,YAAY,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAE9C,KAAK,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;AA4C5C,KAAK,OAAO,GAAG,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;AAEjD,MAAM,MAAM,GAAG,GAAG;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,cAAc,CAAA;IACxB,MAAM,EAAE,YAAY,CAAA;IACpB,KAAK,EAAE,OAAO,CAAA;CACf,CAAA;AA4ZD,wBAAsB,SAAS,CAC7B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,UAAe,GACpB,OAAO,CAAC,GAAG,CAAC,CAad"}

package/package.json

@@ -3,7 +3,7 @@
   "description": "A more opinionated web server for building REST-ful applications",
   "author": "Travis J True",
   "license": "MIT",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "exports": {
     ".": {

package/src/index.ts

@@ -109,10 +109,13 @@ type AppRoutes = {
   socket: SocketRoute[]
 }
 
+type CloseFn = (force?: boolean) => Promise<void>
+
 export type App = {
   server: Server
   commands: SocketCommands
   routes: OutputRoutes
+  close: CloseFn
 }
 
 const ALLOWED_FILES_META = ['meta.js', 'meta.ts']
@@ -132,16 +135,6 @@ const ALLOWED_FILES_METHODS = [
   'delete.ts',
 ]
 
-/* istanbul ignore if */
-if (process.stdin.isTTY) {
-  process.stdin.setRawMode(true)
-}
-
-const rl = readline.createInterface({
-  input: stdin,
-  output: stdout,
-})
-
 function methodNotAllowedHandler (_req: unknown): never {
   throw new MethodNotAllowedError()
 }
@@ -382,8 +375,8 @@ function buildSocketRoutes (mergedRoutes: ChainRoute[]): SocketRoute[] {
   }))
 }
 
-function buildModuleRoutes (routePaths: SocketRoute[]): ModuleRoute[] {
-  return routePaths.map(route => {
+function buildModuleRoutes (socketRoutes: SocketRoute[]): ModuleRoute[] {
+  return socketRoutes.map(route => {
     const handler: EndpointHandler = async (bunReq, server) => {
       const req = buildEndpointRequest(bunReq, server)
 
@@ -494,7 +487,7 @@ function processIO (
   port: number,
   server: Server,
   opts: AppOptions,
-): void {
+): CloseFn {
   const onClose = opts.onClose || (() => {})
 
   console.info(`Running on port: ${port}`)
@@ -502,12 +495,37 @@ function processIO (
   console.info('Press Ctrl+D to gracefully shutdown')
   console.info('')
 
-  /* istanbul ignore next */
-  rl.on('close', async () => {
-    await server.stop()
+  const shutdown = async (force = false): Promise<void> => {
+    await server.stop(force)
     await onClose()
-    process.exit(0)
+  }
+
+  if (!stdin.isTTY) {
+    return shutdown
+  }
+
+  stdin.setRawMode(true)
+
+  const rl = readline.createInterface({
+    input: stdin,
+    output: stdout,
   })
+
+  /* istanbul ignore next */
+  const handleClose = async (): Promise<void> => {
+    await shutdown()
+    process.exit(0)
+  }
+
+  rl.on('close', handleClose)
+
+  return async (force = false) => {
+    rl.off('close', handleClose)
+    rl.close()
+    stdin.setRawMode(false)
+
+    await shutdown(force)
+  }
 }
 
 export async function createApp (
@@ -519,12 +537,12 @@ export async function createApp (
   const routes = await buildRoutes(rootPath, state, opts)
   const server = buildServer(port, routes, state, opts)
   const commands = buildSocketCommands(state)
-
-  processIO(port, server, opts)
+  const close = processIO(port, server, opts)
 
   return {
     routes: routes.output,
     server,
     commands,
+    close,
   }
 }