`@netscript/service`

Service bootstrap builders, health probes, and Hono/oRPC runtime wiring for NetScript applications. This page is written against the package's public surface reported by deno doc. For the full index of packages and plugins return to the reference overview.

The package has three layers. Layer 1 exposes small primitives for health, error, RPC, OpenAPI, and Scalar docs handlers. Layer 2 exposes createService(), a fluent builder that materializes a mountable ServiceApp or starts a listener. Layer 3 exposes defineService(), the preset used by generated service entrypoints.

The service router is always an input to the builder. build() returns a non-listening ServiceApp, which keeps the RFC 14 unified-platform seam open for callers that mount service apps into another host. serve() starts a Deno listener and returns a RunningService handle with stop() for tests, local development, and process supervisors.

Public types are package-owned structural mirrors: callers do not need to import Hono or oRPC types to describe a service surface. Runtime interoperability still uses the real Hono app and oRPC handlers internally. LoggerMiddlewareOptions is re-exported from the sibling @netscript/logger/middleware package because it is a first-party @netscript/* contract, not an upstream vendor surface.

Builder and presets

Symbol	Signature	Description
`createService`	`function createService<T extends ServiceRouter>(router: T, config: ServiceConfig): ServiceBuilder<T>`	Factory function to create a new service builder.
`defineService`	`async function defineService<T extends ServiceRouter>(router: T, options: DefineServiceOptions): Promise<RunningService>`	One-liner preset for creating a fully-configured service.

Health primitives

Symbol	Signature	Description
`createHealthHandler`	`function createHealthHandler(options?: HealthHandlerOptions): ServiceHandler`	Creates a comprehensive health check handler that runs all checks in parallel.
`createLivenessHandler`	`function createLivenessHandler(): ServiceHandler`	Creates a simple liveness check handler.
`createReadinessHandler`	`function createReadinessHandler(checks: Array<() => Promise<boolean>>): ServiceHandler`	Creates a readiness check handler that runs multiple async checks.
`healthChecks`	`const healthChecks: { database; kv; service; custom }`	Pre-built health checks for common dependencies (`database`, `kv`, `service`, `custom`).
`HEALTH_STATUS`	`const HEALTH_STATUS: { healthy; degraded; unhealthy }`	Health status values emitted by service health handlers.

RPC, OpenAPI, and docs handlers

Symbol	Signature	Description
`createRPCHandler`	`function createRPCHandler<T extends ServiceRouter>(router: T, config?: RPCHandlerConfig): FetchHandler`	Creates an oRPC RPC handler for type-safe client communication.
`createRPCPlugins`	`function createRPCPlugins(config: RPCHandlerConfig): ServiceHandlerPlugin[]`	Creates the standard set of oRPC plugins.
`createOpenAPIHandler`	`function createOpenAPIHandler<T extends ServiceRouter>(router: T, config?: RPCHandlerConfig): FetchHandler`	Creates an oRPC OpenAPI handler for REST-style API access.
`createOpenAPISpec`	`function createOpenAPISpec<T extends ServiceRouter>(router: T, config: OpenAPIConfig): ServiceHandler`	Creates an OpenAPI specification endpoint handler.
`createScalarDocs`	`function createScalarDocs(options: ScalarDocsOptions): ServiceHandler`	Creates a Scalar API documentation UI handler.
`createScalarJs`	`function createScalarJs(): ServiceHandler`	Creates a handler to serve the bundled Scalar JS file.

Error and routing handlers

Symbol	Signature	Description
`createErrorHandler`	`function createErrorHandler(serviceName: string): ServiceErrorHandler`	Creates a global error handler for uncaught exceptions.
`createNotFoundHandler`	`function createNotFoundHandler(serviceName: string): ServiceHandler`	Creates a 404 Not Found handler for unmatched routes.

Configuration and option types

Symbol	Kind	Description
`ServiceConfig`	interface	Service configuration options (input to `createService`).
`DefineServiceOptions`	interface	Options for the `defineService` preset.
`ServeOptions`	interface	Options for starting a service listener.
`CorsOptions`	interface	CORS options supported by `withCors()`.
`OpenAPIConfig`	interface	Configuration for OpenAPI spec generation.
`RPCHandlerConfig`	interface	Configuration options for RPC handlers.
`ScalarDocsOptions`	interface	Configuration for the Scalar docs UI.
`HealthHandlerOptions`	interface	Options for `createHealthHandler`.
`LoggerMiddlewareOptions`	interface	Options for the logger middleware (re-exported from `@netscript/logger/middleware`).

Service surface types

Symbol	Kind	Description
`ServiceBuilder`	interface	Fluent builder for configuring and materializing a NetScript service.
`ServiceApp`	interface	Minimal mountable service application returned by `build()`.
`RunningService`	interface	Running service handle returned by `serve()` and `defineService()`.
`RunningServiceAddress`	interface	Network address assigned to a running service listener.
`ServiceContext`	interface	Minimal context shape exposed to service middleware and handlers.
`ServiceRequest`	interface	Minimal request shape exposed to service middleware and handlers.
`ServiceMiddleware`	interface	Middleware function accepted by the service builder.
`ServiceHandler`	interface	Service route handler accepted by the builder route API.
`ServiceHandlerPlugin`	interface	Structural oRPC plugin accepted by service handler factories.
`ServiceErrorHandler`	interface	Error handler used by service applications.
`FetchHandler`	interface	Structural fetch handler used by RPC and OpenAPI service adapters.
`FetchHandlerResult`	interface	Result returned by oRPC-compatible fetch handlers.

Health types

Symbol	Kind	Description
`HealthCheck`	interface	A single health check definition.
`HealthResponse`	interface	Response format for the health endpoint.
`Database`	interface	Database client capable of a health-check query.
`HealthStatus`	type alias	Health status emitted by the service health endpoint (`typeof HEALTH_STATUS[keyof typeof HEALTH_STATUS]`).

Router and context type aliases

Symbol	Signature	Description
`ServiceRouter`	`type ServiceRouter = Record<string, unknown>`	Router definition accepted by the service builder and handler factories.
`ContextFactory`	`type ContextFactory = (context: ServiceContext) => Record<string, unknown>`	Creates per-request service handler context.
`DbContext`	`type DbContext = Record<string, unknown>`	Database context injected into service handler context.

Exports

The following entrypoints are published alongside the root export:

Export	Entrypoint	Purpose
`@netscript/service`	`./mod.ts`	Full service surface (documented above).
`@netscript/service/auth`	`./src/auth/mod.ts`	Service authentication and authorization handlers.
`@netscript/service/rpc-path`	`./src/primitives/rpc-path.ts`	Type-safe RPC route mapping utilities.

Back to the reference overview.