@small-web/kitten-types 1.1.3 → 2.0.0

package/kitten/src/middleware/request-log.d.ts

@@ -0,0 +1,10 @@
+/**
+  Keeps a truncated log of the last 25 request URLs for debugging purposes.
+
+  This could be merged with the stats plugin or expanded to log more than just URLs
+  or even removed altogether in the future. Just keeping it in here for the moment
+  to see if it’s useful for debugging certain types of issues.
+*/
+import type { NextHandler } from 'polka';
+import type { KittenRequest, KittenResponse } from '../types/index.ts';
+export default function (): (request: KittenRequest, response: KittenResponse, next: NextHandler) => void;

package/kitten/src/middleware/sessions.d.ts

@@ -0,0 +1,3 @@
+import type { NextHandler } from 'polka';
+import type { KittenRequest, KittenResponse } from '../types/index.ts';
+export default function (): (request: KittenRequest, response: KittenResponse, next: NextHandler) => Promise<void>;

package/kitten/src/middleware/stats.d.ts

@@ -0,0 +1,8 @@
+/**
+  Stats middleware.
+
+  Logs referrers.
+*/
+import type { NextHandler } from 'polka';
+import type { KittenRequest, KittenResponse } from '../types/index.ts';
+export default function (ownDomainWithHttps: string): (request: KittenRequest, response: KittenResponse, next: NextHandler) => void;

package/kitten/src/middleware/trailing-slashes.d.ts

@@ -0,0 +1,11 @@
+/**
+  Add trailing slash to all URL paths that need one.
+  So, /hello will become /hello/, for example. This avoids
+  issues with relative URLs breaking when the path is missing a trailing
+  slash (e.g., <script src='./index.ts'></script>).
+
+  See: https://stackoverflow.com/questions/31111257/relative-links-on-pages-without-trailing-slash
+*/
+import type { NextHandler } from 'polka';
+import type { KittenRequest, KittenResponse } from '../types/index.ts';
+export default function (): (request: KittenRequest, response: KittenResponse, next: NextHandler) => void;

package/kitten/src/middleware/websocket.d.ts

@@ -0,0 +1,14 @@
+/**
+  WebSocket middleware: development mode only.
+
+  Handles WebSocket connections using the Kitten `ws` mixin to implment hot reload functionality along with the client-side Kitten development time script that’s injected into pages during development.
+
+  On connection, sends server’s boot ID so development-time clients can reliably detect server restarts (the boot ID changes across process starts).
+
+  @returns {import('polka').Middleware<any>}
+*/
+import type { NextHandler } from 'polka';
+import type { KittenRequest, KittenResponse, WebSocket } from '../types/index.ts';
+export default function (): (request: KittenRequest & {
+    ws?: () => Promise<WebSocket>;
+}, _response: KittenResponse, next: NextHandler) => Promise<void>;

package/kitten/src/routes/HttpRoute.d.ts

@@ -0,0 +1,16 @@
+import LazilyLoadedRoute from './LazilyLoadedRoute.ts';
+import type { KittenRequest, KittenResponse } from '../types/index.ts';
+type HttpRouteHandler = (parameterObject: {
+    request: KittenRequest;
+    response: KittenResponse;
+}) => any;
+export default class HttpRoute extends LazilyLoadedRoute {
+    _handler: HttpRouteHandler | undefined;
+    initialise(): Promise<void>;
+    /**
+      Concrete overload that lazily loads the route handler if
+      necessary and handles requests.
+    */
+    lazilyLoadedHandler(request: KittenRequest, response: KittenResponse): Promise<void>;
+}
+export {};

package/kitten/src/routes/LazilyLoadedRoute.d.ts

@@ -0,0 +1,15 @@
+import type { NextHandler } from 'polka';
+import type { KittenRequest, KittenResponse } from '../types/index.ts';
+export default class LazilyLoadedRoute {
+    filePath: string;
+    basePath: string;
+    extension: string;
+    pattern: string;
+    method: string;
+    /**
+     Abstract base class for lazily-loaded routes.
+    */
+    constructor(filePath: string, basePath: string);
+    get handler(): (request: KittenRequest, response: KittenResponse, next?: NextHandler) => Promise<void>;
+    lazilyLoadedHandler(request: KittenRequest, response: KittenResponse, next?: NextHandler): Promise<void>;
+}

package/kitten/src/routes/PageRoute.d.ts

@@ -0,0 +1,54 @@
+import LazilyLoadedRoute from './LazilyLoadedRoute.ts';
+import type { KittenRequest as SharedKittenRequest, KittenResponse as SharedKittenResponse } from '../types/index.ts';
+export interface KittenRequest extends SharedKittenRequest {
+    ws?: () => any;
+}
+export interface KittenResponse extends SharedKittenResponse {
+}
+export type SwapTarget = {
+    before?: string;
+} | {
+    after?: string;
+} | {
+    asFirstChildOf?: string;
+} | {
+    asLastChildOf?: string;
+};
+export interface Slot {
+    default?: string[] | any[];
+    HEAD?: string[];
+    START_OF_BODY?: string[];
+    END_OF_BODY?: string[];
+    BEFORE_LIBRARIES?: string[];
+    AFTER_LIBRARIES?: string[];
+    HTML?: string;
+    [key: string]: any;
+}
+export default class PageRoute extends LazilyLoadedRoute {
+    isClassBasedRoute: boolean;
+    isLive: boolean;
+    source: any;
+    url?: string;
+    lang: string;
+    /**
+      One-time lazy initialisation. Imports the handler and,
+      if present, the page template.
+    */
+    initialise(): Promise<void>;
+    /**
+      Concrete overload that lazily loads the page route handler
+      as necessary and handles requests.
+    */
+    lazilyLoadedHandler(request: KittenRequest, response: KittenResponse): Promise<void>;
+    renderBaseLayoutComponent({ headSlotOverrides, page, request, SLOT }: {
+        headSlotOverrides: Array<string>;
+        page: any;
+        request: KittenRequest;
+        SLOT: Slot;
+    }): string;
+    /**
+      Renders the final HTML given the results of the
+      html tagged template function.
+    */
+    renderHtml(contents: string | string[] | any, page: any, request: KittenRequest): string;
+}

package/kitten/src/routes/PageSocketRoute.d.ts

@@ -0,0 +1,42 @@
+import LazilyLoadedRoute from './LazilyLoadedRoute.ts';
+import type { NextHandler } from 'polka';
+import type { KittenRequest, KittenResponse, WebSocket } from '../types/index.ts';
+type WebSocketWithIsAlive = WebSocket & {
+    isAlive: boolean;
+    id?: string;
+};
+type RequestWithWebSocket = KittenRequest & {
+    ws?: () => Promise<any>;
+};
+export default class PageSocketRoute extends LazilyLoadedRoute {
+    sockets: WebSocketWithIsAlive[];
+    eventHandlers: Record<string, (...args: any[]) => any>;
+    initialised: boolean;
+    /**
+      Create a lazily-loaded PageSocket route instance with the provided file path.
+  
+     (A PageSocket route is a specialised WebSocket route that simplifies streaming
+     updates ot the page it is connected to.)
+    */
+    constructor(filePath: string, basePath: string);
+    /**
+      Lazily load the handler.
+  
+      Unlike in other route types, we’re not loading in the default
+      export here (our _handler() function is already defined, below) but
+      the exported `onConnect()` function from a page route.
+    */
+    lazilyLoadedHandler(request: RequestWithWebSocket, response: KittenResponse, next?: NextHandler): Promise<void>;
+    /**
+      This is a specialised WebSocket route handler specifically for
+      routing to an `onConnect()` handler exported from a page.
+  
+      TODO: Remove redundancy with routes/WebSocketRoute.js
+    */
+    _handler({ request, next }: {
+        request: RequestWithWebSocket;
+        next?: NextHandler;
+        [key: string]: any;
+    }): Promise<void>;
+}
+export {};

package/kitten/src/routes/PostRoute.d.ts

@@ -0,0 +1,64 @@
+import LazilyLoadedRoute from './LazilyLoadedRoute.ts';
+import type { KittenRequest, KittenResponse } from '../types/index.ts';
+/**
+  We convert the file upload metadata returned by Busboy
+  to a leaner format that’s more ergonomic when authoring so
+  we do a little bit of gymlastics with types so our intent
+  is clear and the type checker is happy.
+*/
+type BusboyFileUploadMetadata = {
+    uuid: string;
+    filename: string;
+    file: string;
+    mimetype: string;
+    field: string;
+    encoding: string;
+    truncated: boolean;
+    done: boolean;
+};
+type OriginalRequest = KittenRequest & {
+    files?: Record<string, BusboyFileUploadMetadata | BusboyFileUploadMetadata[]>;
+};
+export declare class Upload {
+    id: string;
+    fileName: string;
+    filePath: string;
+    mimetype: string;
+    field: string;
+    encoding: string;
+    truncated: boolean;
+    done: boolean;
+    constructor(parameters: {
+        id: string;
+        fileName: string;
+        filePath: string;
+        mimetype: string;
+        field: string;
+        encoding: string;
+        truncated: boolean;
+        done: boolean;
+    });
+    /**
+      Returns absolute resource path for accessing this upload via a GET request
+      (content-disposition: inline).
+    */
+    get resourcePath(): string;
+    /**
+      Returns the absolute download path (content-disposition: attachment).
+    */
+    get downloadPath(): string;
+    /**
+      Deletes this uploaded file from the file system and also from the internal database.
+    */
+    delete(): Promise<void>;
+}
+export default class PostRoute extends LazilyLoadedRoute {
+    _handler: Function | undefined;
+    initialise(): Promise<void>;
+    /**
+      Concrete overload that lazily loads the POST route handler if
+      necessary and handles requests.
+    */
+    lazilyLoadedHandler(request: OriginalRequest, response: KittenResponse): Promise<void>;
+}
+export {};

package/kitten/src/routes/StaticRoute.d.ts

@@ -0,0 +1,17 @@
+import type { KittenRequest, KittenResponse } from '../types/index.ts';
+export default class StaticRoute {
+    filePath: string;
+    basePath: string;
+    pattern: string;
+    method: string;
+    /**
+      Represents static routes.
+    */
+    constructor(filePath: string, basePath: string);
+    /**
+      This is a simple static file; serve it as such.
+    */
+    get handler(): ((request: KittenRequest, response: KittenResponse) => Promise<void>) & {
+        filePath?: string;
+    };
+}

package/kitten/src/routes/WebSocketRoute.d.ts

@@ -0,0 +1,21 @@
+import LazilyLoadedRoute from './LazilyLoadedRoute.ts';
+import type { NextHandler } from 'polka';
+import type { KittenRequest, KittenResponse } from '../types/index.ts';
+type RequestWithOptionalWebSocket = KittenRequest & {
+    ws?: () => Promise<any>;
+};
+export default class WebSocketRoute extends LazilyLoadedRoute {
+    connections: any[];
+    __handler: Function | undefined;
+    /**
+     * Create a lazily-loaded WebSocket route instance with the provided file path.
+     */
+    constructor(filePath: string, basePath: string);
+    lazilyLoadedHandler(request: KittenRequest, response: KittenResponse, next?: NextHandler): Promise<void>;
+    _handler({ request, next }: {
+        request: RequestWithOptionalWebSocket;
+        next?: NextHandler;
+        [key: string]: any;
+    }): Promise<void>;
+}
+export {};

package/kitten/src/routes/lib/validator.d.ts

@@ -0,0 +1,18 @@
+/**
+  Use either passed singular or plural form based on value of amount.
+*/
+declare const pluralise: (amount: number, singular: string, plural: string) => string;
+/**
+
+Validates for HTML and accessibility correctness.
+
+@param source - HTML source to validate
+@param filePath - path of current file
+
+**/
+declare function validate(source: string, filePath: string): any[];
+/**
+  Adds validation support to the passed HTML document.
+*/
+export { pluralise, validate };
+export default function addValidationSupportInDevelopment(htmlDocument: string, filePath: string, url: string): string;

package/kitten/src/types/fragments.d.ts

@@ -0,0 +1,14 @@
+type Fragment = (props?: {SLOT?: any}) => string
+
+declare module '*.fragment.html' {
+  const fragment: Fragment
+  export default fragment
+}
+declare module '*.fragment.css' {
+  const fragment: Fragment
+  export default fragment
+}
+declare module '*.fragment.md' {
+  const fragment: Fragment
+  export default fragment
+}