@owlmeans/entrypoint 0.1.18-rc.39 → 0.1.18-rc.40

package/src/types.ts

@@ -1,9 +1,12 @@
 import type { ResolvedServiceRoute, RouteAddress, RouteModel, RouteProtocol } from '@owlmeans/route'
-import type { InitializedService, LazyService, BasicEntrypoint } from '@owlmeans/context'
-import type { AnySchemaObject } from 'ajv'
+import type { InitializedService, LazyService, BasicEntrypoint, EntrypointReference } from '@owlmeans/context'
+import type { AnySchemaObject, JSONSchemaType } from 'ajv'
 import type { EntrypointOutcome } from './consts.js'
 import type { Auth } from '@owlmeans/auth'
 
+import type { AnyShapeSource, entrypointSchemaType, SourceValue, TypeToken, UrlRequest } from './types.local.js'
+import type { createFilterHelper } from './filter.js'
+
 /**
  * A URL unit: an immutable route declaration plus what guards, gates and schemas it answers under.
  *
@@ -151,3 +154,197 @@ export interface EntrypointTransport extends InitializedService {
   readonly protocol: RouteProtocol
   handle: EntrypointHandler
 }
+
+/** A deliberately broad value used only by declarations without an I/O contract. */
+export type OpenValue = object | string | number | boolean | bigint | null | undefined
+
+/** The four independent request sections an entrypoint may declare. */
+export interface RequestShape {
+  body?: OpenValue
+  params?: object
+  query?: object
+  headers?: object
+}
+
+export interface RuntimeRequestSchemas {
+  body?: AnySchemaObject
+  params?: AnySchemaObject
+  query?: AnySchemaObject
+  headers?: AnySchemaObject
+}
+
+export interface RuntimeResponseSchemas {
+  default?: AnySchemaObject
+  byStatus?: Readonly<Record<number, AnySchemaObject>>
+}
+
+/** The runtime schemas and compile-time request/response pair attached to one protocol. */
+export interface EntrypointContract<Request extends RequestShape, Response> {
+  readonly kind: 'entrypoint-contract'
+  readonly requestSchemas: RuntimeRequestSchemas
+  readonly responseSchemas?: RuntimeResponseSchemas
+  readonly requestType?: Request
+  readonly responseType?: Response
+}
+
+/** Runtime fields common to every protocol, regardless of its compile-time request/reply pair. */
+export interface EntrypointProtocolDeclaration {
+  readonly kind: 'entrypoint-protocol'
+  readonly alias: string
+  readonly route: RouteModel
+  readonly contract?: Pick<EntrypointContract<RequestShape, OpenValue>,
+    'kind' | 'requestSchemas' | 'responseSchemas'>
+  readonly sticky: boolean
+  readonly guards: readonly string[]
+  readonly gate?: {
+    readonly alias: string
+    readonly params: readonly string[]
+  }
+}
+
+/** A context-bound entrypoint made from an immutable protocol declaration. */
+export type MaterializedEntrypoint<Protocol extends EntrypointProtocolDeclaration> = CommonEntrypoint & {
+  readonly protocol: Protocol
+}
+
+/** The request accepted by a declaration that intentionally supplies no contract. */
+export interface OpenRequest {
+  body?: object
+  params?: object
+  query?: object
+  headers?: object
+}
+
+/** Addressing and transport controls are never part of an entrypoint's payload contract. */
+export interface CallOptions {
+  auth?: Auth
+  host?: string
+  base?: string | boolean
+  unsecure?: boolean
+  timeout?: number
+  signal?: AbortSignal
+}
+
+/** A type-only contract source, optionally paired with an AJV schema. */
+export type Typed<T> = TypeToken & { readonly value?: T }
+
+/**
+ * A JSON schema carrying the model type it validates.  Use `schema<Model>(...)` once beside the
+ * model; every protocol that consumes it then infers the model without another generic.
+ */
+export type EntrypointSchema<T> = JSONSchemaType<T> & {
+  readonly [entrypointSchemaType]: T
+}
+
+/** A schema or an explicit type-only source for one request/response value. */
+export type ShapeSource<T> = EntrypointSchema<T> | JSONSchemaType<T> | Typed<T>
+
+export interface RequestSources {
+  body?: AnyShapeSource
+  params?: AnyShapeSource
+  query?: AnyShapeSource
+  headers?: AnyShapeSource
+}
+
+/** An access gate declared by a protocol, including inherited parent declarations. */
+export interface EntrypointGate {
+  readonly alias: string
+  readonly params: readonly string[]
+}
+
+export type RequestFromSources<Sources extends RequestSources> =
+  (Sources extends { body: infer Source } ? { body: SourceValue<Source> } : {})
+  & (Sources extends { params: infer Source } ? { params: SourceValue<Source> } : {})
+  & (Sources extends { query: infer Source } ? { query: SourceValue<Source> } : {})
+  & (Sources extends { headers: infer Source } ? { headers: SourceValue<Source> } : {})
+
+export interface EntrypointOptions {
+  sticky?: boolean
+  guards?: string | readonly string[]
+  gate?: {
+    alias: string
+    params?: string | readonly string[]
+  }
+}
+
+export interface EntrypointResult<Response> {
+  value: Response
+  outcome: EntrypointOutcome
+}
+
+export type CallArguments<Request extends RequestShape> = {} extends Request
+  ? [request?: Request & CallOptions]
+  : [request: Request & CallOptions]
+
+export type UrlArguments<Request extends RequestShape> = {} extends UrlRequest<Request>
+  ? [request?: UrlRequest<Request> & CallOptions]
+  : [request: UrlRequest<Request> & CallOptions]
+
+export interface EntrypointRequestMeta {
+  alias: string
+  auth?: Auth
+  entity?: ResolvedEntity
+  path: string
+  canceled?: boolean
+  cancel?: () => void
+}
+
+/**
+ * A protocol request at an implementation boundary.
+ *
+ * Transport metadata and empty request sections remain available to handlers; a declared section
+ * then refines that base shape to its protocol contract.
+ */
+export type HandlerRequest<Request extends RequestShape> = AbstractRequest & Request & EntrypointRequestMeta
+
+/**
+ * An immutable shared declaration.  Its inherited reference type is what gives a context lookup
+ * the exact registered entrypoint type without a consumer-supplied generic.
+ */
+export interface EntrypointProtocol<
+  Request extends RequestShape = RequestShape,
+  Response = OpenValue,
+> extends EntrypointProtocolDeclaration, EntrypointReference<RegisteredEntrypoint<Request, Response>> {
+  readonly contract?: EntrypointContract<Request, Response>
+}
+
+/** The context-bound counterpart of an immutable protocol declaration. */
+export interface RegisteredEntrypoint<Request extends RequestShape, Response> extends BasicEntrypoint {
+  readonly protocol: EntrypointProtocol<Request, Response>
+  call: (...args: CallArguments<Request>) => Promise<Response>
+  invoke: (...args: CallArguments<Request>) => Promise<EntrypointResult<Response>>
+  url: (...args: UrlArguments<Request>) => Promise<string>
+  validate: (...args: CallArguments<Request>) => Promise<boolean>
+}
+
+export type RequestOf<Protocol extends EntrypointProtocolDeclaration> = Protocol extends EntrypointProtocol<infer Request, infer _Response>
+  ? Request
+  : OpenRequest
+
+export type ResponseOf<Protocol extends EntrypointProtocolDeclaration> = Protocol extends EntrypointProtocol<infer _Request, infer Response>
+  ? Response
+  : OpenValue
+
+export type BodyOf<Protocol extends EntrypointProtocolDeclaration> = RequestOf<Protocol> extends { body: infer Body }
+  ? Body
+  : OpenValue
+
+export type ParamsOf<Protocol extends EntrypointProtocolDeclaration> = RequestOf<Protocol> extends { params: infer Params }
+  ? Params
+  : object
+
+export type QueryOf<Protocol extends EntrypointProtocolDeclaration> = RequestOf<Protocol> extends { query: infer Query }
+  ? Query
+  : object
+
+export type HeadersOf<Protocol extends EntrypointProtocolDeclaration> = RequestOf<Protocol> extends { headers: infer Headers }
+  ? Headers
+  : object
+
+export type CallRequestOf<Protocol extends EntrypointProtocolDeclaration> = RequestOf<Protocol> & CallOptions
+
+export interface EntrypointTree {
+  readonly [key: string]: EntrypointProtocolDeclaration | EntrypointTree
+}
+
+export type FilterHelper = ReturnType<typeof createFilterHelper>

package/src/utils.ts

@@ -0,0 +1,5 @@
+/**
+ * Service alias a transport registers under. The default protocol is the web one, so an application
+ * that binds nothing keeps talking HTTP.
+ */
+export const transportAlias = (protocol: string = 'http') => `transport:${protocol}`