@fastang/core 0.1.0-alpha.1 → 0.1.0-alpha.2

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.1.0-alpha.2
+
+- Accept native Fastify per-route options in API and contract helpers, including typed hooks, body limits, route config and HEAD behavior. File routing and shared contract schemas remain authoritative.
+
+- Add read-only `fastang routes` inspection with page/layout/metadata ancestry and explicit API methods, including versioned JSON output.
+
+- Validate FastAng configuration before starting the development server, using the same loader and checks as production builds.
+
+- Optional TypeBox API contracts infer Fastify handler types and Angular JSON client requests and successful responses.
+- Shared contracts reuse runtime schemas, check file-route consistency and encode API URLs explicitly.
+
 ## 0.1.0-alpha.1
 
 - Preserve separate Set-Cookie headers and allow explicit per-dispatch forwarding to HTML responses.

package/README.md

@@ -1,7 +1,7 @@
 # @fastang/core
 
 Experimental FastAng runtime and tooling for Angular + Fastify applications.
-Version 0.1.0-alpha.1 is an experimental alpha. Public APIs may change between alpha releases.
+Version 0.1.0-alpha.2 is an experimental alpha. Public APIs may change between alpha releases.
 
 The package contains compiled JavaScript and TypeScript declarations. Angular,
 Fastify, Vite and the Angular compiler are explicit peer dependencies so the app
@@ -25,6 +25,7 @@ Registry installation is available once both alpha packages have been published.
 - `@fastang/core/angular`: `createRenderer(RootComponent, createAppConfig)` with per-request providers, HTTP transfer cache and router redirects.
 - `@fastang/core/vite`: `defineFastangConfig()` for Angular compilation, generated routes and server/client boundaries.
 - `@fastang/core/config`, `/api`, `/server`, `/http-server`, `/node-handler`, `/listen`, `/render-context`: focused imports.
+- `/contracts`, `/contract-route`, `/http-client`: optional shared TypeBox contracts, Fastify registration and Angular JSON requests (from `0.1.0-alpha.2`). Install `@sinclair/typebox` to use contracts.
 - `/routes`, `/adapters/vercel`, `/adapters/vercel-plan`, `/vite-plugin`: lower-level tooling APIs; still experimental.
 
 `createServer()` and `createApiServer()` accept a `registerApi(app)` callback.
@@ -52,3 +53,26 @@ npm pack --workspace @fastang/core --pack-destination /tmp
 
 Install the tarball into a copy of `examples/starter`. No global CLI, repository
 source files or website assets are required by the installed package.
+
+## Inspect file routes
+
+From `0.1.0-alpha.2`, `fastang routes` lists page paths in matching order with their source
+files, ancestor layouts and metadata files, followed by explicit API methods.
+Use `fastang routes --json` for a JSON document with `schemaVersion: 1`, `pages`
+and `api` arrays.
+
+Inspection uses the same discovery and collision checks as generation. It does
+not import application modules, evaluate configuration, write generated files,
+build the app or start a server. Paths describe file conventions: custom Angular
+router prefixes, routes registered by plugins and Fastify's implicit HEAD routes
+are not included. `**` denotes an Angular catch-all; API catch-alls use `*`.
+The output does not report prerendering or deployment-function assignment.
+
+## Native API route options
+
+From `0.1.0-alpha.2`, `defineApiRoute()` forwards native Fastify route options, including hooks,
+`bodyLimit`, `config`, `exposeHeadRoute` and route error handlers. Method and URL
+remain controlled by file routing. Hooks preserve the request/reply generic types;
+a second generic describes custom route config. Schemas are optional, as in
+Fastify. `defineContractRoute()` from `/contract-route` accepts the same options,
+except that its schema comes from the shared contract.

package/dist/api.d.ts

@@ -1,7 +1,7 @@
-import type { FastifyInstance, FastifySchema, HTTPMethods, RawReplyDefaultExpression, RawRequestDefaultExpression, RawServerDefault, RouteGenericInterface, RouteHandlerMethod } from 'fastify';
-type Handler<T extends RouteGenericInterface> = RouteHandlerMethod<RawServerDefault, RawRequestDefaultExpression, RawReplyDefaultExpression, T>;
-export declare function defineApiRoute<T extends RouteGenericInterface>(options: {
-    schema: FastifySchema;
-    handler: Handler<T>;
-}): (app: FastifyInstance, method: HTTPMethods, url: string) => void;
-export {};
+import type { FastifyInstance, HTTPMethods, RawReplyDefaultExpression, RawRequestDefaultExpression, RawServerDefault, RouteGenericInterface, RouteOptions } from 'fastify';
+/** Native Fastify route options; the file convention owns method and URL. */
+export type ApiRouteOptions<T extends RouteGenericInterface = RouteGenericInterface, ContextConfig = Record<string, unknown>> = Omit<RouteOptions<RawServerDefault, RawRequestDefaultExpression, RawReplyDefaultExpression, T, ContextConfig>, 'method' | 'url'> & {
+    method?: never;
+    url?: never;
+};
+export declare function defineApiRoute<T extends RouteGenericInterface, ContextConfig = Record<string, unknown>>(options: ApiRouteOptions<T, ContextConfig>): (app: FastifyInstance, method: HTTPMethods, url: string) => void;

package/dist/api.js

@@ -1,4 +1,3 @@
-// I tipi rimangono nel closure: nessun cast quando si registra la rotta generata.
 export function defineApiRoute(options) {
     return (app, method, url) => { app.route({ ...options, method, url }); };
 }

package/dist/cli.js

@@ -3,12 +3,14 @@ const command = process.argv[2];
 try {
     if (command === 'generate')
         await (await import("./routes.js")).generate();
+    else if (command === 'routes')
+        await import("./commands/inspect-routes.js");
     else if (command === 'dev')
         await import("./commands/dev.js");
     else if (command === 'build')
         await import("./commands/build.js");
     else if (!command || command === '--help' || command === '-h')
-        console.log('Usage: fastang <dev|generate|build> [--vercel]');
+        console.log('Usage: fastang <dev|generate|build|routes>\n  build [--vercel]\n  routes [--json]');
     else
         throw new Error(`Unknown command: ${command}`);
 }

package/dist/commands/build.js

@@ -10,15 +10,11 @@ import { mkdir, rm, writeFile } from 'node:fs/promises';
 import { resolve, dirname } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { build } from 'vite';
-import { loadConfigFromFile } from 'vite';
 import { prepareVercelPlan } from "../adapters/vercel-plan.js";
 import { buildVercelOutput } from "../adapters/vercel.js";
 import { staticFile } from "../static-path.js";
-import { validateConfig } from "../config.js";
-const loaded = await loadConfigFromFile({ command: 'build', mode: 'production' }, 'fastang.config.ts');
-if (!loaded)
-    throw new Error('Missing fastang.config.ts');
-const config = validateConfig(loaded.config);
+import { loadFastangConfig } from "./load-config.js";
+const config = await loadFastangConfig('build');
 const vercel = process.argv.includes('--vercel');
 const paths = [...new Set(config.prerender)];
 const vercelPlan = vercel ? await prepareVercelPlan(paths, config.vercel) : undefined;

package/dist/commands/dev-server.js

@@ -6,6 +6,8 @@ import { listen } from "../listen.js";
 import { tsImport } from 'tsx/esm/api';
 import { resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { loadFastangConfig } from "./load-config.js";
+await loadFastangConfig('serve');
 const { configureServer } = await tsImport(pathToFileURL(resolve('src/server/plugins.ts')).href, import.meta.url);
 const { registerApi } = await tsImport(pathToFileURL(resolve('.fastang/api.ts')).href, import.meta.url);
 let vite;

package/dist/commands/inspect-routes.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/inspect-routes.js

@@ -0,0 +1,25 @@
+import { inspectRoutes } from "../routes.js";
+const args = process.argv.slice(3);
+if (args.length > 1 || args.some(argument => argument !== '--json'))
+    throw new Error('Usage: fastang routes [--json]');
+const manifest = await inspectRoutes();
+if (args.includes('--json'))
+    console.log(JSON.stringify(manifest, null, 2));
+else {
+    console.log('File-based page routes (matching order)');
+    for (const page of manifest.pages) {
+        console.log(`PAGE ${page.path}  ${page.file}`);
+        for (const layout of page.layouts)
+            console.log(`  layout ${layout.path}  ${layout.file}${layout.metadata ? `  metadata: ${layout.metadata}` : ''}`);
+        if (page.metadata)
+            console.log(`  metadata ${page.metadata}`);
+    }
+    if (!manifest.pages.length)
+        console.log('(none)');
+    console.log('\nFile-based API routes');
+    for (const route of manifest.api)
+        console.log(`${route.method.padEnd(7)} ${route.path}  ${route.file}`);
+    if (!manifest.api.length)
+        console.log('(none)');
+    console.log('\nFile conventions only: application router prefixes, plugin routes and implicit HEAD routes are not included.');
+}

package/dist/commands/load-config.d.ts

@@ -0,0 +1,3 @@
+import { type FastangConfig } from '../config.ts';
+/** Use the same loader and validation before initializing either server or build. */
+export declare function loadFastangConfig(command: 'serve' | 'build'): Promise<FastangConfig>;

package/dist/commands/load-config.js

@@ -0,0 +1,9 @@
+import { loadConfigFromFile } from 'vite';
+import { validateConfig } from "../config.js";
+/** Use the same loader and validation before initializing either server or build. */
+export async function loadFastangConfig(command) {
+    const loaded = await loadConfigFromFile({ command, mode: command === 'build' ? 'production' : 'development' }, 'fastang.config.ts');
+    if (!loaded)
+        throw new Error('Missing fastang.config.ts');
+    return validateConfig(loaded.config);
+}

package/dist/contract-route.d.ts

@@ -0,0 +1,7 @@
+import type { FastifyInstance, HTTPMethods } from 'fastify';
+import type { ApiRouteOptions } from './api.ts';
+import type { ApiContract, ApiRouteTypes } from './contracts.ts';
+/** Infer handler types and reuse validation/serialization from the shared contract. */
+export declare function defineContractRoute<C extends ApiContract, ContextConfig = Record<string, unknown>>(contract: C, options: Omit<ApiRouteOptions<ApiRouteTypes<C>, ContextConfig>, 'schema'> & {
+    schema?: never;
+}): (app: FastifyInstance, method: HTTPMethods, url: string) => void;

package/dist/contract-route.js

@@ -0,0 +1,8 @@
+/** Infer handler types and reuse validation/serialization from the shared contract. */
+export function defineContractRoute(contract, options) {
+    return (app, method, url) => {
+        if (method !== contract.method || url !== contract.path)
+            throw new Error(`API contract mismatch: file route ${method} ${url}, contract ${contract.method} ${contract.path}`);
+        app.route({ ...options, method, url, schema: contract.schema });
+    };
+}

package/dist/contracts.d.ts

@@ -0,0 +1,46 @@
+import type { Static, TSchema } from '@sinclair/typebox';
+export interface ApiSchemas {
+    params?: TSchema;
+    querystring?: TSchema;
+    body?: TSchema;
+    response: Record<number, TSchema>;
+}
+export interface ApiContract<S extends ApiSchemas = ApiSchemas> {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    schema: S;
+}
+type Field<S, K extends PropertyKey> = S extends Record<K, infer T extends TSchema> ? Static<T> : never;
+type InputFields<C extends ApiContract> = (C['schema'] extends {
+    params: TSchema;
+} ? {
+    params: Field<C['schema'], 'params'>;
+} : {}) & (C['schema'] extends {
+    querystring: TSchema;
+} ? {
+    query: Field<C['schema'], 'querystring'>;
+} : {}) & (C['schema'] extends {
+    body: TSchema;
+} ? {
+    body: Field<C['schema'], 'body'>;
+} : {});
+export type ApiInput<C extends ApiContract> = keyof InputFields<C> extends never ? Record<string, never> : InputFields<C>;
+type UrlFields<C extends ApiContract> = Pick<InputFields<C>, Extract<keyof InputFields<C>, 'params' | 'query'>>;
+export type ApiUrlInput<C extends ApiContract> = keyof UrlFields<C> extends never ? Record<string, never> : UrlFields<C>;
+export type ApiReply<C extends ApiContract> = {
+    [K in keyof C['schema']['response']]: C['schema']['response'][K] extends TSchema ? Static<C['schema']['response'][K]> : never;
+};
+export type ApiSuccess<C extends ApiContract> = {
+    [K in keyof ApiReply<C>]: K extends string | number ? `${K}` extends `2${string}` ? ApiReply<C>[K] : never : never;
+}[keyof ApiReply<C>];
+export type ApiRouteTypes<C extends ApiContract> = {
+    Params: Field<C['schema'], 'params'>;
+    Querystring: Field<C['schema'], 'querystring'>;
+    Body: Field<C['schema'], 'body'>;
+    Reply: ApiReply<C>;
+};
+/** Public JSON schemas only: do not import a server handler into a contract module. */
+export declare function defineApiContract<const S extends ApiSchemas>(contract: ApiContract<S>): ApiContract<S>;
+/** Encodes scalar path values and flat query values; never stringifies objects. */
+export declare function apiUrl<C extends ApiContract>(contract: C, input: ApiUrlInput<C>): string;
+export {};

package/dist/contracts.js

@@ -0,0 +1,51 @@
+const pathPattern = /^\/api\/(?:[\w-]+|:[a-zA-Z_]\w*)(?:\/(?:[\w-]+|:[a-zA-Z_]\w*))*$/;
+/** Public JSON schemas only: do not import a server handler into a contract module. */
+export function defineApiContract(contract) {
+    if (!['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(contract.method))
+        throw new Error('Unsupported contract method');
+    if (!pathPattern.test(contract.path))
+        throw new Error('Contract path must be a local /api/... path with static or named segments');
+    const parameters = contract.path.split('/').filter(part => part.startsWith(':')).map(part => part.slice(1));
+    const schema = contract.schema.params;
+    if (schema && schema.type !== 'object')
+        throw new Error('schema.params must be an object schema');
+    const properties = Object.keys(schema?.properties ?? {});
+    if (new Set(parameters).size !== parameters.length || parameters.length !== properties.length || parameters.some(name => !properties.includes(name) || !schema?.required?.includes(name))) {
+        throw new Error('Contract path parameters must match required schema.params properties');
+    }
+    if (contract.method === 'GET' && contract.schema.body)
+        throw new Error('GET contracts do not support bodies');
+    if (!Object.keys(contract.schema.response).some(status => /^2\d\d$/.test(status)) || Object.keys(contract.schema.response).some(status => !/^[1-5]\d\d$/.test(status)))
+        throw new Error('Contract response schemas need HTTP statuses and at least one 2xx response');
+    return contract;
+}
+/** Encodes scalar path values and flat query values; never stringifies objects. */
+export function apiUrl(contract, input) {
+    if (!pathPattern.test(contract.path))
+        throw new Error('Invalid local API contract path');
+    const values = input;
+    const names = contract.path.split('/').filter(part => part.startsWith(':')).map(part => part.slice(1));
+    if (Object.keys(values.params ?? {}).some(name => !names.includes(name)))
+        throw new Error('Unknown API path parameter');
+    const scalar = (value) => {
+        if (typeof value === 'string' || typeof value === 'boolean' || (typeof value === 'number' && Number.isFinite(value)))
+            return String(value);
+        throw new Error('API URL values must be strings, finite numbers or booleans');
+    };
+    const path = contract.path.split('/').map(part => {
+        if (!part.startsWith(':'))
+            return part;
+        const value = scalar(values.params?.[part.slice(1)]);
+        if (!value || value === '.' || value === '..')
+            throw new Error('Empty or dot path parameters are not supported');
+        return encodeURIComponent(value);
+    }).join('/');
+    const query = new URLSearchParams();
+    for (const [key, value] of Object.entries(values.query ?? {})) {
+        if (value === undefined)
+            continue;
+        for (const item of Array.isArray(value) ? value : [value])
+            query.append(key, scalar(item));
+    }
+    return path + (query.size ? '?' + query.toString() : '');
+}

package/dist/http-client.d.ts

@@ -0,0 +1,28 @@
+import { HttpClient, type HttpContext, type HttpHeaders } from '@angular/common/http';
+import type { Observable } from 'rxjs';
+import { type ApiContract, type ApiInput, type ApiSuccess } from './contracts.ts';
+export interface ApiRequestOptions {
+    headers?: HttpHeaders | Record<string, string | string[]>;
+    context?: HttpContext;
+    withCredentials?: boolean;
+    credentials?: RequestCredentials;
+    transferCache?: boolean | {
+        includeHeaders?: string[];
+    };
+}
+type Arguments<C extends ApiContract> = C['schema'] extends {
+    params: unknown;
+} | {
+    querystring: unknown;
+} | {
+    body: unknown;
+} ? [input: ApiInput<C>, options?: ApiRequestOptions] : [input?: ApiInput<C>, options?: ApiRequestOptions];
+/** Thin JSON client: native HttpClient interceptors, errors and transfer cache apply. */
+export declare function createApiClient(http: HttpClient): {
+    request<C extends ApiContract>(contract: C, ...args: Arguments<C>): Observable<ApiSuccess<C>>;
+};
+/** Call in an Angular injection context, just like inject(HttpClient). */
+export declare function injectApiClient(): {
+    request<C extends ApiContract>(contract: C, ...args: Arguments<C>): Observable<ApiSuccess<C>>;
+};
+export {};

package/dist/http-client.js

@@ -0,0 +1,16 @@
+import { inject } from '@angular/core';
+import { HttpClient } from '@angular/common/http';
+import { apiUrl } from "./contracts.js";
+/** Thin JSON client: native HttpClient interceptors, errors and transfer cache apply. */
+export function createApiClient(http) {
+    return {
+        request(contract, ...args) {
+            const [input = {}, options = {}] = args;
+            return http.request(contract.method, apiUrl(contract, input), {
+                ...options, body: input.body, observe: 'body', responseType: 'json',
+            });
+        },
+    };
+}
+/** Call in an Angular injection context, just like inject(HttpClient). */
+export function injectApiClient() { return createApiClient(inject(HttpClient)); }

package/dist/routes.d.ts

@@ -16,6 +16,26 @@ export interface PageRouteNode {
 }
 export declare function buildPageTree(files: string[]): PageRouteNode[];
 export declare function discoverPageTree(directory: string): Promise<PageRouteNode[]>;
+export interface RouteInspection {
+    schemaVersion: 1;
+    pages: {
+        path: string;
+        file: string;
+        metadata?: string;
+        layouts: {
+            path: string;
+            file: string;
+            metadata?: string;
+        }[];
+    }[];
+    api: {
+        method: string;
+        path: string;
+        file: string;
+    }[];
+}
+/** Inspect file conventions without evaluating application modules or writing files. */
+export declare function inspectRoutes(root?: string): Promise<RouteInspection>;
 export interface PageRoutesSourceOptions {
     pagesImport: string;
     selectedFile?: string;

package/dist/routes.js

@@ -177,6 +177,33 @@ export function buildPageTree(files) {
 export async function discoverPageTree(directory) {
     return buildPageTree(await listFiles(directory));
 }
+/** Inspect file conventions without evaluating application modules or writing files. */
+export async function inspectRoutes(root = process.cwd()) {
+    const [tree, endpoints] = await Promise.all([
+        discoverPageTree(resolve(root, 'src/app/pages')),
+        discover(resolve(root, 'src/server/api'), 'api'),
+    ]);
+    const pages = [];
+    const describe = (node) => ({
+        path: '/' + node.fullPath,
+        file: 'src/app/pages/' + node.file,
+        ...(node.metadata ? { metadata: 'src/app/pages/' + node.metadata } : {}),
+    });
+    function visit(nodes, layouts) {
+        for (const node of nodes) {
+            if (node.kind === 'layout')
+                visit(node.children ?? [], [...layouts, describe(node)]);
+            else
+                pages.push({ ...describe(node), layouts });
+        }
+    }
+    visit(tree, []);
+    return {
+        schemaVersion: 1,
+        pages,
+        api: endpoints.map(route => ({ method: route.method, path: '/api' + (route.path ? '/' + route.path : ''), file: 'src/server/api/' + route.file })),
+    };
+}
 async function writeChanged(file, content) {
     await mkdir(dirname(file), { recursive: true });
     if (await readFile(file, 'utf8').catch(() => '') !== content)

package/dist/vite-plugin.js

@@ -3,7 +3,7 @@ export function isServerModule(id) {
     const path = id.replaceAll('\\', '/').split('?')[0];
     return /\/(src\/server|framework|\.fastang)\//.test(path)
         || /\.server\.[cm]?[jt]s$/.test(path)
-        || /\/(?:@fastang\/core|packages\/core)\/(?:src|dist)\/(?:index|server|http-server|node-handler|listen|angular|api|routes|vite|vite-plugin|cli|commands\/.*|adapters\/.*)\.[cm]?[jt]s$/.test(path);
+        || /\/(?:@fastang\/core|packages\/core)\/(?:src|dist)\/(?:index|server|http-server|node-handler|listen|angular|api|contract-route|routes|vite|vite-plugin|cli|commands\/.*|adapters\/.*)\.[cm]?[jt]s$/.test(path);
 }
 export function fastang() {
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastang/core",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "type": "module",
   "description": "Angular rendering, Fastify APIs and file-based routing.",
   "license": "MIT",
@@ -78,6 +78,18 @@
     "./vite": {
       "types": "./dist/vite.d.ts",
       "import": "./dist/vite.js"
+    },
+    "./contracts": {
+      "types": "./dist/contracts.d.ts",
+      "import": "./dist/contracts.js"
+    },
+    "./contract-route": {
+      "types": "./dist/contract-route.d.ts",
+      "import": "./dist/contract-route.js"
+    },
+    "./http-client": {
+      "types": "./dist/http-client.d.ts",
+      "import": "./dist/http-client.js"
     }
   },
   "scripts": {
@@ -104,7 +116,8 @@
     "vite": "8.3.4",
     "typescript": "~6.0.2",
     "@angular/compiler-cli": "22.2.3",
-    "@angular/build": "22.2.3"
+    "@angular/build": "22.2.3",
+    "@sinclair/typebox": "^0.34.41"
   },
   "repository": {
     "type": "git",
@@ -119,5 +132,10 @@
   "homepage": "https://fastang.dev",
   "bugs": {
     "url": "https://github.com/daclab-dev/fastang/issues"
+  },
+  "peerDependenciesMeta": {
+    "@sinclair/typebox": {
+      "optional": true
+    }
   }
 }