@kosmojs/lib 0.0.26 → 0.0.28

package/pkg/routes/paths.d.ts

@@ -0,0 +1,25 @@
+import type { PathToken } from "@kosmojs/core";
+/**
+ * Parse a filesystem route path into structured PathToken array.
+ *
+ * Uses path-to-regexp v8 AST for parsing, with directory-friendly syntax:
+ *   - [param]     => required param - :param
+ *   - {param}     => optional param - {:param}
+ *   - {...param}  => splat - {*param}
+ *
+ * Direct :param syntax is prohibited outside {} to avoid ambiguity.
+ * Inside {} it is treated as path-to-regexp power syntax and used as-is.
+ *
+ * Examples:
+ *   Required:       [id], [name]
+ *   Optional:       {name}, {format}
+ *   Splat:          {...path}
+ *   Mixed segments: shop/[id]-{name}
+ *   Power syntax:   {-v:version{-:pre}}, :name{@:version{.:min}}.js
+ * */
+export declare const pathTokensFactory: (path: string, { transformStaticValue, }?: {
+    transformStaticValue?: (v: string) => string;
+}) => Array<PathToken>;
+export declare const createPathPattern: (tokens: Array<PathToken>) => string;
+export declare const createHonoPattern: (tokens: Array<PathToken>) => string;
+export declare const normalizeStaticValue: (value: string) => string;

package/pkg/routes/resolve.d.ts

@@ -1,3 +1,3 @@
-import type { RouteEntry, RouteResolverCacheFactory, SourceFolder } from "../types";
+import { type RouteEntry, type RouteResolverCacheFactory, type SourceFolder } from "@kosmojs/core";
 import type { ResolverSignature } from "./base";
 export declare const resolverFactory: (sourceFolder: SourceFolder, cacheFactory?: RouteResolverCacheFactory) => Record<"pageLayoutResolver" | "pageRouteResolver" | "apiUseResolver" | "apiRouteResolver", (entry: RouteEntry) => ResolverSignature>;

package/pkg/routes/templates.d.ts

@@ -0,0 +1,2 @@
+export { default as resolvedTypes } from "#templates/resolved-types.hbs";
+export { default as typesFile } from "#templates/types.hbs";

package/pkg/typebox.d.ts

@@ -1,2 +1,2 @@
-import type { SourceFolder } from "./types";
+import { type SourceFolder } from "@kosmojs/core";
 export declare const typeboxLiteralText: (text: string, sourceFolder: SourceFolder) => string;

package/pkg/vite.d.ts

@@ -0,0 +1,4 @@
+import type { Plugin } from "vite";
+export declare const vitePlugins: {
+    nodePrefix: () => Plugin;
+};

package/pkg/defaults.d.ts

@@ -1,14 +0,0 @@
-export declare const defaults: {
-    appPrefix: string;
-    srcPrefix: string;
-    libPrefix: string;
-    coreDir: string;
-    srcDir: string;
-    libDir: string;
-    configDir: string;
-    apiDir: string;
-    pagesDir: string;
-    entryDir: string;
-    fetchDir: string;
-    refineTypeName: string;
-};

package/pkg/types.d.ts

@@ -1,314 +0,0 @@
-import type { IncomingMessage, ServerResponse } from "node:http";
-import type { ResolvedType } from "tfusion";
-import type { UserConfig } from "vite";
-import type { HTTPMethod, ValidationTarget } from "@kosmojs/api";
-export type FolderConfig = Pick<UserConfig, "publicDir" | "plugins" | "html" | "css" | "json" | "oxc" | "assetsInclude" | "server" | "logLevel" | "customLogger" | "clearScreen" | "envDir" | "envPrefix" | "optimizeDeps" | "ssr" | "dev" | "build" | "define" | "resolve"> & {
-    /** Generators to run for this source folder (validation, fetch clients, OpenAPI, etc.) */
-    generators?: Array<GeneratorFactory>;
-    /**
-     * Name to use for custom runtime validation refinements.
-     * @default "VRefine"
-     * */
-    refineTypeName?: string;
-};
-export type SourceFolder = {
-    /** Source folder name, e.g. "front", "admin", "app" */
-    name: string;
-    /** Resolved folder configuration */
-    config: FolderConfig;
-    /** Absolute path to the project root */
-    root: string;
-    /** Base URL this source folder is served from, e.g. "/" or "/admin" */
-    baseurl: string;
-    /** Base URL for API routes, e.g. "/api" */
-    apiurl: string;
-    /** output directory name, configured as `distDir` in package.json */
-    distDir: string;
-};
-export type ProjectSettings = {
-    root: string;
-    sourceFolders: Array<SourceFolder>;
-    command: "serve" | "build";
-    devPort: number;
-};
-export type PathTokenStaticPart = {
-    type: "static";
-    value: string;
-};
-export type PathTokenParamPart = {
-    type: "param";
-    kind: "required" | "optional" | "splat";
-    name: string;
-    /** codegen-safe identifier: sanitized name + crc suffix when needed */
-    const: string;
-};
-export type PathToken = {
-    kind: "static" | "param" | "mixed";
-    orig: string;
-    pattern: string;
-    parts: Array<PathTokenStaticPart | PathTokenParamPart>;
-};
-/**
- * route entry as found in file-system, before any processing
- * */
-export type RouteEntry = {
-    id: string;
-    name: string;
-    folder: string;
-    file: string;
-    fileFullpath: string;
-    pathTokens: Array<PathToken>;
-    pathPattern: string;
-};
-export type NestedRouteEntry = {
-    index: Omit<RouteEntry, "fileFullpath"> | undefined;
-    layout: Omit<RouteEntry, "fileFullpath"> | undefined;
-    parent: string | undefined;
-    children: Array<NestedRouteEntry>;
-};
-export type ApiRoute = RouteEntry & {
-    params: {
-        id: string;
-        schema: Array<PathTokenParamPart>;
-        resolvedType: ResolvedType | undefined;
-    };
-    numericParams: Array<string>;
-    optionalParams: boolean;
-    methods: Array<string>;
-    typeDeclarations: Array<TypeDeclaration>;
-    validationDefinitions: Array<ValidationDefinition>;
-    referencedFiles: Array<string>;
-};
-export type ApiUse = RouteEntry;
-export type PageRoute = RouteEntry & {
-    params: {
-        schema: Array<PathTokenParamPart>;
-    };
-};
-export type PageLayout = RouteEntry;
-export type ResolvedEntry = {
-    kind: "apiRoute";
-    entry: ApiRoute;
-} | {
-    kind: "apiUse";
-    entry: ApiUse;
-} | {
-    kind: "pageRoute";
-    entry: PageRoute;
-} | {
-    kind: "pageLayout";
-    entry: PageLayout;
-};
-export type ValidationDefinition = {
-    method: HTTPMethod;
-    runtimeValidation?: boolean | undefined;
-    customErrors?: Record<string, string> | undefined;
-} & ({
-    target: "response";
-    variants: Array<{
-        id: string;
-        status: number;
-        contentType: string | undefined;
-        body: string | undefined;
-        resolvedType?: ResolvedType | undefined;
-    }>;
-} | {
-    target: Exclude<ValidationTarget, "response">;
-    contentType?: string | undefined;
-    schema: {
-        id: string;
-        text: string;
-        resolvedType?: ResolvedType | undefined;
-    };
-});
-export type RequestValidationDefinition = Exclude<ValidationDefinition, {
-    target: "response";
-}>;
-export type ResponseValidationDefinition = Extract<ValidationDefinition, {
-    target: "response";
-}>;
-export type TypeDeclaration = {
-    text: string;
-    importDeclaration?: {
-        name: string;
-        alias?: string | undefined;
-        path: string;
-    };
-    exportDeclaration?: {
-        name: string;
-        alias?: string | undefined;
-        path?: string | undefined;
-    };
-    typeAliasDeclaration?: {
-        name: string;
-    };
-    interfaceDeclaration?: {
-        name: string;
-    };
-    enumDeclaration?: {
-        name: string;
-    };
-};
-export type PathParams = {
-    text: string;
-    properties: Array<{
-        name: string;
-        type: string;
-    }>;
-};
-export type WatcherEvent = {
-    kind: "create" | "update" | "delete";
-    file: string;
-};
-export type WatchHandler = (entries: Array<ResolvedEntry>, event?: WatcherEvent) => Promise<void>;
-type GeneratorFactoryReturn = {
-    watch: WatchHandler;
-    build: (entries: Array<ResolvedEntry>) => Promise<void>;
-};
-export type DefineGenerator = <O extends Record<string, unknown> | undefined = undefined, R extends boolean = false>(factory: [O] extends [undefined] ? () => GeneratorFactory : (o: O) => GeneratorFactory<O>, m?: GeneratorMeta) => [O] extends [undefined] ? () => GeneratorFactory : [R] extends [true] ? (o: O) => GeneratorFactory<O> : (o?: O) => GeneratorFactory<O>;
-export type DefineGeneratorFactory = <O extends Record<string, unknown> | undefined = undefined, R extends boolean = false>(f: GeneratorFactory<O, R>) => GeneratorFactory<O, R>;
-export type GeneratorFactory<O extends Record<string, unknown> | undefined = undefined, R extends boolean = false> = [O] extends [undefined] ? (f: SourceFolder) => Promise<GeneratorFactoryReturn> : [R] extends [true] ? (f: SourceFolder, o: O) => Promise<GeneratorFactoryReturn> : (f: SourceFolder, o?: O) => Promise<GeneratorFactoryReturn>;
-export type GeneratorMeta = {
-    name: string;
-    slot?: "api" | "fetch" | "ssr";
-    /**
-     * Package dependencies required by this generator.
-     * The dev plugin checks installation status before running.
-     * */
-    dependencies?: Record<string, string>;
-    devDependencies?: Record<string, string>;
-    /**
-     * Enables type resolution for generators that require fully resolved type information.
-     *
-     * When `true`, types are resolved to their flattened representations before
-     * generator execution, making complete type data available.
-     * */
-    resolveTypes?: boolean;
-};
-type RouterSetup<R> = {
-    clientRouter: () => R | Promise<R>;
-    serverRouter: (ssrOpts: {
-        url: URL;
-    }) => R | Promise<R>;
-};
-export type RouterFactory<AppT, RouteT, RouterT> = (factory: (app: AppT, routes: Array<RouteT>) => RouterSetup<RouterT> | Promise<RouterSetup<RouterT>>) => (app: AppT, routes: Array<RouteT>, ssrOpts?: {
-    url: URL;
-}) => RouterT | Promise<RouterT>;
-type RenderSetup = {
-    clientRender: () => void | Promise<void>;
-    serverRender: () => void | Promise<void>;
-};
-export type RenderFactory = (factory: () => RenderSetup | Promise<RenderSetup>) => void | Promise<void>;
-/**
- * Minimal shape of Vite's manifest.json entries.
- * */
-export type SSRManifestEntry = {
-    file: string;
-    src?: string;
-    isEntry?: boolean;
-    isDynamicEntry?: boolean;
-    css?: string[];
-    assets?: string[];
-    imports?: string[];
-    dynamicImports?: string[];
-};
-/**
- * SSR environment options passed to user-defined
- * renderToString / renderToStream functions.
- * */
-export type SSROptions = {
-    template: string;
-    manifest: Record<string, SSRManifestEntry>;
-    criticalCss: Array<{
-        text: string;
-        path: string;
-    }>;
-    request: IncomingMessage;
-    response: ServerResponse;
-};
-/**
- * Return type for string-based SSR rendering.
- *
- * - `head` is optional, user may choose to:
- *    - insert the provided critical CSS (opt.criticalCss),
- *    - override it (e.g. remove some styles),
- *    - or supply additional <meta>/<link>/<style> tags.
- *
- * - `html` is the main server-rendered body markup for hydration.
- * */
-export type SSRStringReturn = {
-    head?: string;
-    html: string;
-};
-/**
- * SSR string mode
- *
- * Returns head + html, synchronously or async.
- *
- * The server will:
- * - insert returned `head` into the HTML template
- * - place returned `html` into the body placeholder
- * */
-export type SSRString = (url: URL, opt: SSROptions) => SSRStringReturn | Promise<SSRStringReturn>;
-/**
- * SSR stream mode
- *
- * Writes directly to the HTTP response.
- *
- * Responsibility of the user/render function:
- * - insert head + critical CSS at the correct time (before first flush)
- * - manage partial flushing, suspense boundaries, etc.
- *
- * The server will NOT modify the response body in this mode,
- * thus the renderer **must call `response.end()`** when streaming is finished,
- * otherwise the HTTP request will remain open and the client will hang.
- * */
-export type SSRStream = (url: URL, opt: SSROptions) => void | Promise<void>;
-/**
- * Default exported object from the SSR entry module (e.g. entry/server.ts).
- * */
-export type SSRSetup = {
-    /**
-     * The server calls render functions with current request URL and SSROptions.
-     *
-     * If both are provided, `renderToStream` takes precedence since streaming
-     * enables earlier flushing and improved Time-to-First-Byte (TTFB).
-     * `renderToString` will only be used if a streaming renderer is not available.
-     * */
-    renderToString?: SSRString;
-    renderToStream?: SSRStream;
-    /**
-     * Controls whether the SSR server should handle static asset requests (JS, CSS, images, fonts, etc.)
-     *
-     *   true  (default)
-     *     → All built client assets are served directly from memory by SSR server.
-     *     → Easiest setup - no external file server required.
-     *
-     *   false
-     *     → A reverse proxy/CDN *must* serve all static files.
-     *     → Otherwise any asset URL requested from browser (JS/CSS/img) will return `404`.
-     *
-     * Notes:
-     *   - `criticalCss.text` can still be inlined regardless of this setting.
-     *   - `criticalCss.url` remains provided for `<link>` usage,
-     *     but loading that URL is the responsibility of the external static server.
-     *
-     * This option enables deployments where SSR and static delivery
-     * are cleanly separated (e.g., Node behind nginx / cloud static hosting).
-     * */
-    serveStaticAssets?: boolean;
-};
-export type SSRFactory = (factory: () => SSRSetup | Promise<SSRSetup>) => SSRSetup | Promise<SSRSetup>;
-export type RouteResolverCache = {
-    hash: number;
-    referencedFiles: Record<string, number>;
-} & Pick<ApiRoute, "params" | "methods" | "numericParams" | "typeDeclarations" | "validationDefinitions">;
-export type RouteResolverCacheFactory = (route: Pick<ApiRoute, "id" | "file" | "fileFullpath">, sourceFolder: SourceFolder, extraContext?: object) => {
-    get: (opt?: {
-        validate?: boolean;
-    }) => Promise<RouteResolverCache | undefined>;
-    set: (cache: Omit<RouteResolverCache, "hash" | "referencedFiles"> & {
-        referencedFiles: Array<string>;
-    }) => Promise<RouteResolverCache>;
-};
-export {};