fusion-framework 1.3.0 → 2.0.0

package/README.md

@@ -16,6 +16,8 @@ From this repo:
 cd crates/fusion-node && npm install && npm run build:debug
 ```
 
+**Important:** `napi build` must use `--js false` so it does not overwrite `index.js` (the FusionApp / middleware layer). The npm scripts already pass this flag.
+
 Scaffold with [Fusion Tool](https://github.com/cipherunits/fusion-tool):
 
 ```bash
@@ -35,7 +37,7 @@ export const ItemModule = route('/api/[module]/{id}')(
   },
 )
 
-const MIDDLEWARE = [] // register with app.use() — see securityHeaders, cors, requestId, …
+const MIDDLEWARE = [] // add middleware explicitly, e.g. frameworkHeaders()
 
 settings.ensureLoaded()
 const app = new FusionApp(getSettings())

package/index.d.ts

@@ -1,148 +1,87 @@
-export class App {
-  constructor()
-  route(method: string, path: string, handler: (req: FusionRequest) => FusionResponse | string): void
-  listen(host: string, port: number): Promise<void>
-}
-
-export class Settings {
-  constructor()
-  loadJson(path?: string | null, env?: string | null, extraRoots?: string[]): void
-  ensureLoaded(extraRoots?: string[]): void
-  merge(values: Record<string, unknown>): void
-  get(key: string, defaultValue?: unknown): unknown
-  readonly host: string
-  readonly port: number
-  readonly debug: boolean
-  readonly env: string
-}
-
-export class FusionBaseApi {
-  request: FusionRequest
-  constructor(request: FusionRequest)
-  readonly method: string
-  readonly path: string
-  readonly body: string
-  readonly headers: Record<string, string>
-  readonly params: Record<string, string>
-  readonly query: Record<string, string>
-  readonly state: Record<string, unknown>
-  response(body?: unknown, status?: number, headers?: Record<string, string>): FusionResponse
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+export declare function getHttpMethods(): Array<string>
+export declare function apiResourceNameJs(className: string): string
+export declare function resolveRoutePathJs(template: string, className: string): string
+export declare function coerceParamJs(raw: string, kind?: string | undefined | null): unknown
+export interface HttpStatusCode {
+  name: string
+  code: number
 }
-
-export class HTTPException extends Error {
-  status: number
-  detail: unknown
-  headers: Record<string, string>
-  constructor(status: number, detail?: unknown, headers?: Record<string, string>)
-  toResponse(): FusionResponse
-}
-
-export class FusionApp {
-  constructor(settings?: Partial<FusionSettings>)
-  use(middleware: FusionMiddleware): void
-  mount(): void
-  listen(host?: string, port?: number): Promise<void>
+export declare function getHttpStatusCodes(): Array<HttpStatusCode>
+export interface HttpHeaderConstant {
+  name: string
+  value: string
 }
-
-export type RouteOptions = {
-  tags?: string[]
-  desc?: string
-  title?: string
-  version?: string
-  deprecated?: boolean
-  middleware?: FusionMiddleware[]
-  roles?: string[]
-  roleClaim?: string
-  roleStateKey?: string
+export declare function getHttpHeaderConstants(): Array<HttpHeaderConstant>
+export declare function headerAttachment(filename: string): Record<string, string>
+export declare function headerInline(filename?: string | undefined | null): Record<string, string>
+export declare function headerContentType(mediaType: string, charset?: string | undefined | null): Record<string, string>
+export declare function headerLocation(url: string): Record<string, string>
+export declare function headerCacheControl(value: string): Record<string, string>
+export declare function headerDownload(filename: string, mediaType?: string | undefined | null): Record<string, string>
+export declare function getFingerprintHeaders(): Record<string, string>
+/** True when the client prefers JSON (`Accept` or `?format=json`). */
+export declare function prefersJsonJs(accept?: string | undefined | null, formatQuery?: string | undefined | null): boolean
+/** Render a Tera template file relative to `templates_root` (default `"templates"`). */
+export declare function renderTemplateJs(templateName: string, context: JsJson, templatesRoot?: string | undefined | null): string
+export interface PaginationParams {
+  page: number
+  pageSize: number
+  offset: number
 }
-
-export function router(path: string, options?: RouteOptions): <T>(ApiClass: T) => T
-/** Alias of `router`. */
-export function route(path: string, options?: RouteOptions): <T>(ApiClass: T) => T
-
-export function bearerJwt(options?: {
-  stateKey?: string
-  header?: string
-  verify?: (token: string) => Record<string, unknown> | null
-}): FusionMiddleware
-
-export function requireRoles(...roles: string[]): FusionMiddleware
-export function requireRoles(options: {
-  roles: string[]
-  claim?: string
-  stateKey?: string
-}): FusionMiddleware
-
-export function runMiddlewareChain(
-  request: FusionRequest,
-  middlewares: FusionMiddleware[],
-  handler: (request: FusionRequest) => unknown | Promise<unknown>,
-): Promise<unknown>
-
-export function apiResourceName(cls: { name: string } | string): string
-export function resolveRoutePath(path: string, cls: { name: string }): string
-export function configure(settings: Record<string, unknown>): FusionSettings
-export function getSettings(): FusionSettings
-export function run(
-  options?: string | { settingsModule?: string; middleware?: FusionMiddleware[] },
-): Promise<FusionApp>
-export function coerceParam(raw: string, kind?: string): unknown
-export function getHttpMethods(): string[]
-export function apiResourceNameJs(className: string): string
-export function resolveRoutePathJs(template: string, className: string): string
-export function coerceParamJs(raw: string, kind?: string): unknown
-
-export const settings: Settings
-export const status: Record<string, number>
-export const header: HeaderModule
-export const HTTP_METHODS: string[]
-
-export interface HeaderModule {
-  [name: string]: string | ((...args: any[]) => Record<string, string>)
-  CONTENT_TYPE: string
-  CONTENT_DISPOSITION: string
-  LOCATION: string
-  AUTHORIZATION: string
-  APPLICATION_JSON: string
-  APPLICATION_OCTET_STREAM: string
-  APPLICATION_PDF: string
-  attachment(filename: string): Record<string, string>
-  inline(filename?: string | null): Record<string, string>
-  contentType(mediaType: string, charset?: string | null): Record<string, string>
-  location(url: string): Record<string, string>
-  cacheControl(value: string): Record<string, string>
-  download(filename: string, mediaType?: string | null): Record<string, string>
-  fingerprint(): Record<string, string>
-}
-
-export interface FusionSettings {
-  host: string
-  port: number
-  debug: boolean
-  env?: string
+export declare function parsePagination(query: object, defaultPageSize?: number | undefined | null, maxPageSize?: number | undefined | null): PaginationParams
+export declare function paginatedBody(items: unknown, total: number, params: PaginationParams): unknown
+/** Apply `cache.*` from a Settings instance to the process-wide cache. */
+export declare function cacheConfigure(settings: Settings): void
+/** Install a driver explicitly (default moka). */
+export declare function cacheConfigureDriver(driver?: string | undefined | null, maxCapacity?: number | undefined | null, defaultTtl?: number | undefined | null): void
+export declare function cacheSet(key: string, value: JsJson, ttl?: number | undefined | null): void
+export declare function cacheGet(key: string): unknown
+export declare function cacheDelete(key: string): boolean
+export declare function cacheExists(key: string): boolean
+export declare function cacheGetOrSet(key: string, default: JsJson, ttl?: number | undefined | null): unknown
+export declare function cacheDeleteOrSet(key: string, value: JsJson, ttl?: number | undefined | null): unknown
+export declare function cacheExistsOrSet(key: string, value: JsJson, ttl?: number | undefined | null): boolean
+export declare function cacheDriver(): string
+export declare function cacheClear(): void
+export declare function cacheReset(): void
+export declare function cacheSnapshot(): unknown
+export declare function cachePanelContext(): unknown
+/**
+ * Spawn a JS function on the Tokio background runtime. Returns task id.
+ *
+ * Uses `call_async` so status becomes `done` only after the JS callback runs
+ * (sync `Blocking` can return before the Node event loop drains the TSFN).
+ */
+export declare function taskSpawn(callback: (...args: any[]) => any): string
+/** Spawn a JS function after `delay_ms` milliseconds. */
+export declare function taskSpawnAfter(delayMs: number, callback: (...args: any[]) => any): string
+/** Cancel a background task by id. */
+export declare function taskCancel(id: string): boolean
+/** Status string for a task id, or null if unknown. */
+export declare function taskStatus(id: string): string | null
+/** Reset the task registry (tests). */
+export declare function taskReset(): void
+/** JSON snapshot of tracked background tasks. */
+export declare function taskSnapshot(): unknown
+export declare class Settings {
+  constructor()
+  loadJson(path?: string | undefined | null, envName?: string | undefined | null, extraRoots?: Array<string> | undefined | null): void
+  ensureLoaded(extraRoots?: Array<string> | undefined | null): void
+  merge(values: unknown): void
+  get(key: string, default?: unknown | undefined | null): unknown
+  get host(): string
+  get port(): number
+  get debug(): boolean
+  get reload(): boolean
+  get env(): string
 }
-
-export interface FusionRequest {
-  method: string
-  path: string
-  body: string
-  headers: Record<string, string>
-  params: Record<string, string>
-  query: Record<string, string>
-  state?: Record<string, unknown>
+export declare class App {
+  constructor()
+  route(method: string, path: string, handler: (...args: any[]) => any): void
+  listen(host: string, port: number): Promise<void>
 }
-
-export type FusionMiddleware = (
-  request: FusionRequest,
-  callNext: (request: FusionRequest) => unknown | Promise<unknown>,
-) => unknown | Promise<unknown>
-
-export function frameworkHeaders(): FusionMiddleware
-
-export type FusionResponse =
-  | string
-  | {
-      status?: number
-      body?: unknown
-      headers?: Record<string, string>
-    }