@small-web/kitten-types 1.1.5 → 2.0.0

package/index.d.ts

@@ -3,38 +3,18 @@
 
   This entry point re-exports Kitten types for use in explicit annotations.
 
+  The types themselves are generated from Kitten’s TypeScript source code
+  (see kitten/ – regenerated via `npm run sync-types` in the Kitten repository),
+  so Kitten’s implementation is the single source of truth.
+
   Side-effect: Brings `declare global { var kitten }` into scope for any project that depends on this package.
 */
 
+/// <reference path="./kitten/third-party-libraries-with-missing-type-information/index.d.ts" />
+
 import './global.d.ts'
 import './fragments.d.ts'
 
 // Reusable types, re-exported for explicit annotations
 // (e.g. `import type { KittenRequest } from '@small-web/kitten-types'`).
-export type {
-  Session,
-  WebSocket,
-  BufferLike,
-  slugify,
-  Polka,
-  MarkdownIt,
-  Upload,
-  LazilyLoadedRoute,
-  MessageSender,
-  Listener,
-  KittenComponent,
-  KittenPage,
-  ParsedURL,
-  PolkaResponse,
-  PolkaRequest,
-  KittenRequest,
-  KittenResponse,
-  KittenPostRequest,
-  Point,
-  Signature
-} from './types.d.ts'
-
-export type { yaml } from './types.d.ts'
-
-// Also export hand-written global namespace shape, in case an author wants to reference it explicitly (e.g. `typeof kitten`).
-export type { kitten } from './global.d.ts'
+export type * from './kitten/src/types/index.d.ts'

package/kitten/src/AppDatabase.d.ts

@@ -0,0 +1,10 @@
+/**
+  Initialise the default database of the app we’re serving.
+  This can either be via the database app module defined in
+  the app, or, if one does not exist, the default untyped
+  Kitten database.
+*/
+export default class Database {
+    path: string | null;
+    initialise(): Promise<void>;
+}

package/kitten/src/AppRepository.d.ts

@@ -0,0 +1,101 @@
+/**
+  App class
+
+  Represents the git repository of the app that Kitten is currently serving.
+
+  (Only relevant in production.)
+*/
+import Version from './lib/Version.ts';
+import type { SimpleGit } from 'simple-git';
+export default class AppRepository {
+    path: string;
+    git: SimpleGit;
+    kittenVersion: Version;
+    remoteTags: Array<string> | undefined;
+    lastRemoteTagUpdate: Date | undefined;
+    originRemoteUrl: string | undefined;
+    hasOrigin: boolean | undefined;
+    currentVersion: string | undefined;
+    latestAvailableCommit: string | undefined;
+    usesKittenVersioning: boolean | undefined;
+    manualUpdateAvailable: boolean | undefined;
+    currentApiVersion: number | undefined;
+    currentAppVersion: number | undefined;
+    tags: string[] | undefined;
+    tagsByApiAndAppVersion: [number, number][] | undefined;
+    latestVersionByApiVersion: number[] | undefined;
+    compatibleTags: string[] | undefined;
+    incompatibleTags: string[] | undefined;
+    latestApiVersion: number | undefined;
+    latestAppVersion: number | undefined;
+    latestVersion: string | undefined;
+    latestCompatibleAppVersion: number | undefined;
+    latestCompatibleVersion: string | undefined;
+    static instance: AppRepository | undefined;
+    static isBeingInitialisedAsSingleton: boolean;
+    /** Matches Kitten version tag strings in the form '<number>.<number>' */
+    static kittenVersionRegExp: RegExp;
+    /**
+      Singleton accessor.
+  
+      Use this method to get an initialised/updated instance.
+  
+      You can always call the update() method again later to get the latest data
+      from the remote repository.
+    */
+    static getInstance(): Promise<AppRepository>;
+    /**
+      Create an instance (should only be called in production).
+    */
+    constructor();
+    /**
+      Updates the app to the latest compatible version.
+    */
+    upgradeAppToLatestCompatibleVersion(): Promise<void>;
+    /**
+      Updates the app to the latest available commit.
+    */
+    upgradeAppToLatestAvailableCommit(): Promise<void>;
+    /**
+      Updates the app to the specified version tag.
+    */
+    updateAppToVersion(versionTag: string): Promise<void>;
+    /**
+      Updates the app repository with the latest information and content.
+  
+      After this method is run, you should have all tags and their content available locally so
+      you can simply use the checkout() method to update the application to the required version.
+    */
+    update(): Promise<void>;
+    get hasCompatibleAppVersion(): boolean;
+    get canBeUpgraded(): boolean;
+    get hasNewerApiVersion(): boolean;
+    /**
+      Returns the string 'upgrade' or 'downgrade' based on whether
+      going from the current app version to the provided version string
+      would be an upgrade or a downgrade.
+  
+      If lowercase is false, the string is returned in sentence case.
+  
+      Does not handle the versions being include. For that, see the
+      isEqualToVersion() method.
+    */
+    upgradeOrDowngrade(versionTag: string, lowercase?: boolean): false | "downgrade" | "Downgrade" | "upgrade" | "Upgrade";
+    isEqualToVersion(versionTag: string): boolean;
+    UpdateButtonComponent(): ({ type, version, small }: {
+        type?: string | undefined;
+        version?: string | undefined;
+        small?: boolean | undefined;
+    }) => string | string[] | Promise<string | string[]>;
+    VersionComponent({ version, compatible, brief }: {
+        version: string;
+        compatible?: boolean;
+        brief?: boolean;
+    }): string | string[] | Promise<string | string[]>;
+    CurrentAppVersionComponent(): () => string | string[] | Promise<string | string[]>;
+    AllAvailableVersionsComponent(): string | string[] | Promise<string | string[]> | (() => string | string[] | Promise<string | string[]>);
+    /**
+      Display app version if Kitten is running in production.
+    */
+    displayAppVersion(): void;
+}

package/kitten/src/AutomaticUpdates.d.ts

@@ -0,0 +1,21 @@
+import AppRepository from './AppRepository.ts';
+import KittenPackage from './lib/KittenPackage.ts';
+export default class AutomaticUpdates {
+    static instance: AutomaticUpdates;
+    running: boolean;
+    lastCheck: Date;
+    kittenPackage: KittenPackage | undefined;
+    appRepository: AppRepository | undefined;
+    intervalId: ReturnType<typeof setInterval> | undefined;
+    get interval(): number;
+    set interval(intervalInMiliseconds: number);
+    static getInstance(): AutomaticUpdates;
+    start(): Promise<void>;
+    requestRestart(): void;
+    updateLastCheck(): void;
+    checkForUpdates(): Promise<void>;
+    get intervalInHours(): number;
+    timeToNextCheck(): number;
+    timeToNextCheckPretty(): string | number;
+    stop(): void;
+}

package/kitten/src/Files.d.ts

@@ -0,0 +1,61 @@
+/**
+  Files: handles the files in the project.
+
+  Copyright ⓒ 2021-present, Aral Balkan (mail@ar.al)
+  Small Technology Foundation (https://small-tech.org)
+  License: AGPL version 3.0.
+*/
+import Watcher from 'watcher';
+export declare class FileEventDetails {
+    itemType: string;
+    eventType: string;
+    itemPath: string;
+    constructor(itemType?: string, eventType?: string, itemPath?: string);
+}
+type FilesByExtension = Record<string, string[]>;
+export declare class FilesByExtensionCategoryType {
+    [categoryType: string]: FilesByExtension;
+    constructor();
+}
+/**
+  Async filter function.
+
+  Thanks to: https://stackoverflow.com/a/62820464
+*/
+export declare function asyncFilter(array: any[], predicate: (value: any, index: number, array?: any[]) => any): Promise<any[]>;
+/**
+  Checks if passed symlink is within the root
+  directory of the project we’re serving and
+  thus whether it is safe.
+*/
+export declare function isSafeSymlink(symlink: string): Promise<boolean>;
+export default class Files extends EventTarget {
+    static isBeingInstantiatedByFactoryMethod: boolean;
+    /**
+      Static factory method: constructs a Files instance, asynchronously
+      initialises it, and returns the list of files found organised by
+      their extension category type.
+    */
+    static new(basePath?: string): Promise<Files>;
+    watcher: Watcher;
+    pathToWatch: string;
+    byExtensionCategoryType: FilesByExtensionCategoryType;
+    /**
+      Find files at given base path and start watching for changes.
+    */
+    constructor(basePath: string);
+    initialise(): Promise<void>;
+    /**
+      Adds file to the list of files.
+    */
+    addFile(filePath: string): void;
+    /**
+      Notifies file listeners that an action has happened on a file.
+    */
+    notifyListeners(fileEventDetails: FileEventDetails): Promise<void>;
+    /**
+      Closes the watcher.
+    */
+    close(): void;
+}
+export {};

package/kitten/src/GlobalInternalDatabase.d.ts

@@ -0,0 +1,22 @@
+/**
+  Initialise Kitten’s global internal database (kitten.__db).
+
+  (That’s two underscores to – uhum – underscore the fact that this
+  is really, really internal so don’t go messing in here. *makes scary noises*
+  Here, have a ghost emoji: 👻)
+
+  Unlike Kitten‘s internal and app databases, this database is
+  scoped to the Kitten instance, *not* to the app that Kitten is serving.
+*/
+declare class State {
+    isBeingDeployedByDomain: boolean;
+    constructor(properties?: {});
+}
+export type GlobalInternalDatabaseType = {
+    state: State;
+};
+export default class GlobalInternalDatabase {
+    static __db: GlobalInternalDatabaseType | null;
+    static initialise(): Promise<GlobalInternalDatabaseType>;
+}
+export {};

package/kitten/src/InternalDatabase.d.ts

@@ -0,0 +1,7 @@
+/**
+  Initialise Kitten’s own internal database (kitten._db).
+*/
+export default class InternalDatabase {
+    path: string | null;
+    initialise(): Promise<void>;
+}

package/kitten/src/REPL.d.ts

@@ -0,0 +1,5 @@
+/**
+  Sets up Kitten REPL (either an interactive one if running locally or on a socket if running as a daemon).
+
+*/
+export default function (domainWithPort: string): void;

package/kitten/src/Routes.d.ts

@@ -0,0 +1,41 @@
+/**
+  Kitten Routes
+
+  Copyright ⓒ 2021-present, Aral Balkan
+  Small Technology Foundation
+  License: AGPL version 3.0.
+*/
+import Files, { FileEventDetails } from './Files.ts';
+import StaticRoute from './routes/StaticRoute.ts';
+import type { LazilyLoadedRoute } from './types/index.ts';
+export type RouteDictionary = Record<string, LazilyLoadedRoute | StaticRoute>;
+export default class Routes {
+    routes: Record<string, RouteDictionary>;
+    basePath: string;
+    files: Files | undefined;
+    static isBeingInstantiatedByFactoryMethod: boolean;
+    /**
+      Returns the routes for the passed base path.
+  
+      (The default base path is the primary place being served, as kept
+      in the `basePath` environment variable.)
+    */
+    static getRoutes(basePath?: string): Promise<Record<string, RouteDictionary>>;
+    /**
+      Private constructor.
+    */
+    constructor(basePath: string);
+    /**
+      Creates and returns the routes at the base path.
+    */
+    initialise(): Promise<Record<string, RouteDictionary>>;
+    /**
+      Handle file change events.
+    */
+    handleFileChange(event: CustomEvent<FileEventDetails>): void;
+    /**
+     Creates routes of a certain category type.
+    */
+    createRoutesOfCategoryType(categoryType: string): void;
+    createRoutes(): void;
+}

package/kitten/src/Server.d.ts

@@ -0,0 +1,76 @@
+/**
+  Kitten Server.
+
+  Copyright © 2021-present, Aral Balkan
+  Small Technology Foundation
+  License: AGPL version 3.0.
+*/
+import { WebSocketServer } from 'ws';
+import AutomaticUpdates from './AutomaticUpdates.ts';
+import AppRepository from './AppRepository.ts';
+import http from 'node:http';
+import type { KittenPolka } from './types/index.ts';
+import type { RouteDictionary } from './Routes.ts';
+export type ServerOptions = {
+    domains?: Array<string>;
+    domain?: string;
+    port?: number | boolean;
+    aliases?: string | Array<string>;
+    open?: boolean;
+    'working-directory'?: string;
+    'domain-token'?: string;
+    'small-web-host-domain'?: string;
+    settingsPath?: string;
+    domainToken?: string;
+    smallWebHostDomain?: string;
+    minVersion?: string;
+    ipv4?: boolean;
+    ipv6?: boolean;
+    ipOnly?: boolean;
+};
+export default class Server {
+    /** Singleton instance. */
+    static instance: Server;
+    static isBeingConstructedViaFactoryMethod: boolean;
+    options: ServerOptions;
+    port: number;
+    domain: string | undefined;
+    open: boolean | undefined;
+    app: KittenPolka;
+    projectUploadsPath: string | undefined;
+    appRepository: AppRepository | undefined;
+    automaticUpdates: AutomaticUpdates | undefined;
+    routes: Record<string, RouteDictionary> | undefined;
+    kittenSettingsApplicationRoutes: Record<string, RouteDictionary> | undefined;
+    server: any;
+    wss: WebSocketServer | undefined;
+    /**
+      Singleton factory method.
+  
+      Await this instead of calling `new Server(…)` and
+      `await server.initialise()`` manually.
+  
+      Returns a promise for a reference to the server singleton,
+      that resolves immediately if it exists, and otherwise
+      resolves once it is created and initialised.
+    */
+    static getInstanceAsync(options: ServerOptions): Promise<Server>;
+    /**
+      Create server instance using passed options.
+    */
+    constructor();
+    /**
+      Create server instance using passed options.
+    */
+    initialise(options: ServerOptions): Promise<void>;
+    /**
+      Node http(s) upgrade event handler
+      (https://nodejs.org/api/http.html#event-upgrade)
+  
+      Implementation based on express-websocket and tinyws, to keep
+      some of the modern interface of tinyws (async/await syntax)
+      while avoiding the client connection timeout issue in tinyws.
+      (See https://codeberg.org/kitten/app/issues/113).
+    */
+    upgradeHandler(request: http.IncomingMessage, socket: import('node:net').Socket, head: Buffer): any;
+}

package/kitten/src/ServerError.d.ts

@@ -0,0 +1,6 @@
+import type { NextHandler } from 'polka';
+import type { KittenRequest, KittenResponse } from './types/index.ts';
+/**
+  Formats and displays server errors.
+*/
+export default function (error: any, request: KittenRequest, response: KittenResponse, _next?: NextHandler): Promise<void>;

package/kitten/src/Sessions.d.ts

@@ -0,0 +1,32 @@
+import EventEmitter from 'node:events';
+import type { KittenRequest, KittenResponse } from './types/index.ts';
+/**
+  Represents an active session.
+
+  Important: since sessions can be deleted during the lifecycle of a server and since
+  you can listen for events on sessions, these need to be cleaned up before a session
+  object is destroyed. As we don’t have destructors in JavaScript, you must call the
+  cleanUp() method manually deleting a session.
+*/
+export declare class Session extends EventEmitter {
+    redirectToAfterSignIn: string | undefined;
+    id: string;
+    createdAt: number;
+    authenticated: boolean;
+    constructor({ id, createdAt, authenticated, ...customData }: {
+        id: string;
+        createdAt?: number;
+        authenticated?: boolean;
+        [key: string]: any;
+    });
+    hasExpired(): boolean;
+}
+export default class Sessions {
+    static instance: Sessions | null;
+    /**
+      Singleton accessor.
+    */
+    static getInstance(): Sessions;
+    constructor();
+    session(request: KittenRequest, response: KittenResponse): Promise<Session>;
+}

package/kitten/src/Uploads.d.ts

@@ -0,0 +1,20 @@
+import { Upload } from './routes/PostRoute.ts';
+import type { KittenRequest, KittenResponse } from './types/index.ts';
+/**
+  Uploads collection class.
+
+  Persisted in the internal database at `_db.uploads`.
+*/
+export default class Uploads {
+    [id: string]: any;
+    constructor(parameters?: {});
+    get(id: string): Upload;
+    length(): number;
+    all(): Upload[];
+    allIds(): string[];
+    delete(id: string): Promise<void>;
+}
+/**
+  Download handler (GET route) for uploaded files.
+*/
+export declare function downloadHandler(): (request: KittenRequest, response: KittenResponse) => void;

package/kitten/src/Utils.d.ts

@@ -0,0 +1,79 @@
+import type { ServerOptions } from './Server.ts';
+/**
+  Display error in console and exit process.
+*/
+export declare function exitWithError(message: string): never;
+/**
+  Determine which places to listen at.
+*/
+export declare function getDomainsAndPort(options: ServerOptions): Promise<{
+    domains: string[];
+    port: number | boolean;
+}>;
+/**
+  Calculate the base path used by the Kitten server to find files in the served app.
+*/
+export declare function setBasePath(workingDirectory: string, pathToServe: string): string;
+/**
+  Returns unique project identifier based on the path of the project
+  that can be used as the name of a directory.
+*/
+export declare function getProjectIdentifierForDomain(domain: string, port: number): string;
+export declare const HTTP_METHODS: string[];
+export declare const BACKEND_EXTENSIONS: string[];
+export declare const FRONTEND_EXTENSIONS: string[];
+export declare const DEPENDENCY_EXTENSIONS: string[];
+export declare const DYNAMIC_ROUTE_EXTENSIONS: string[];
+export declare const STATIC_ROUTE_EXTENSIONS: string[];
+export declare const ALL_ROUTE_EXTENSIONS: string[];
+export declare const extensionCategories: Record<string, string[]>;
+export declare const supportedExtensionsRegExp: string;
+/**
+  Since Polka does not handle unicode in paths correctly
+  (see https://github.com/lukeed/polka/issues/187), we have to
+  split the file path and URI encode each component ourselves.
+*/
+export declare const encodeFilePath: (filePath: string) => string;
+/**
+  Inverse of encodeFilePath. Used when we want to avoid
+  double escaping of file paths.
+*/
+export declare const decodeFilePath: (filePath: string) => string;
+/**
+  Returns the complete extension (e.g., page.js not just .js)
+  of the passed file path. Works with any number of extensions,
+  returning the last two without a dot at the start.
+*/
+export declare function extensionOfFilePath(filePath: string): string;
+/**
+  Given a file path, derives the unique class name for its route.
+*/
+export declare function classNameFromFilePath(filePath: string, basePath: string): string;
+/**
+  Derives the route pattern for the passed file path based on the base path.
+*/
+export declare function routePatternFromFilePath(filePath: string, basePath: string): string;
+/**
+  Converts a route in the form of, e.g.,
+  '/some_thing/with/underscores-and-hyphens' to
+  SomeThingWithUnderscoresAndHyphensPage.
+*/
+export declare function classNameFromRoutePattern(pattern: string): string;
+export declare const kittenAppPath: string;
+/**
+  Run passed command (either 'ci' or 'install') on the given module path.
+*/
+export declare function npm(command: 'ci' | 'install', modulePath: string): boolean;
+/**
+  Runs npm ci on the passed module path.
+*/
+export declare function runNpmCiOnModulePath(modulePath: string): void;
+/**
+  db namespace for JSDB database-related utility functions.
+*/
+export declare class db {
+    /**
+      Given a JSDB change string, returns the dot-separated keypath of the changed property.
+    */
+    static keypathForChange(change: string): string;
+}

package/kitten/src/cli/commands/db.d.ts

@@ -0,0 +1,48 @@
+/**
+  Commands for viewing, tailing, and deleting database and table information.
+
+  Copyright © 2023-present Aral Balkan, Small Technology Foundation.
+  Licensed under GNU AGPL version 3.0.
+*/
+import InternalDatabase from '../../InternalDatabase.ts';
+import AppDatabase from '../../AppDatabase.ts';
+import type { ServerOptions, TailOptions } from '../index.ts';
+type Databases = {
+    internalDatabase: InternalDatabase;
+    appDatabase: AppDatabase;
+    domain: string;
+    port: number;
+};
+/**
+  Initialise databases (internal and app).
+*/
+export declare function initialiseDatabases(options: ServerOptions): Promise<Databases>;
+/**
+  Show database information for default database.
+*/
+export declare function showDefaultDatabaseInformationCommand(tableName: string | undefined, options: ServerOptions): Promise<void>;
+/**
+  Show database information for internal database.
+*/
+export declare function showInternalDatabaseInformationCommand(tableName: string | undefined, options: ServerOptions): Promise<void>;
+/**
+  Delete whole database or specified table in default database.
+*/
+export declare function deleteDefaultDatabaseCommand(tableName: string | undefined, options: ServerOptions): Promise<void>;
+/**
+  Delete whole database or specified table in internal database.
+*/
+export declare function deleteInternalDatabaseCommand(tableName: string | undefined, options: ServerOptions): Promise<void>;
+/**
+  Show database information for default database.
+*/
+export declare function tailDefaultDatabaseTableCommand(tableName: string, options: TailOptions): Promise<void>;
+/**
+  Show database information for internal database.
+*/
+export declare function tailInternalDatabaseTableCommand(tableName: string, options: TailOptions): Promise<void>;
+/**
+  Show head and tail summary of specified table and follow additions to it.
+*/
+export declare function tailDatabaseTableCommand(tableName: string, options: TailOptions, internal: boolean): Promise<void>;
+export {};

package/kitten/src/cli/commands/deploy.d.ts

@@ -0,0 +1,16 @@
+/**
+  Kitten command-line interface (CLI): deploy command.
+
+  Deploys an app from a Git repository as a
+  systemd --user service.
+
+  Copyright ⓒ 2021-present, Aral Balkan
+  Small Technology Foundation
+
+  License: AGPL version 3.0.
+*/
+import type { DeploymentOptions } from '../index.ts';
+/**
+  @param gitHttpsCloneUrl git clone url (HTTPS)
+*/
+export default function deploy(gitHttpsCloneUrl: string, options: DeploymentOptions): Promise<void>;

package/kitten/src/cli/commands/disable.d.ts

@@ -0,0 +1,9 @@
+/**
+  Kitten command-line interface (CLI): disable command.
+
+  Copyright ⓒ 2022-present, Aral Balkan
+  Small Technology Foundation
+
+  License: AGPL version 3.0.
+*/
+export default function disable(_options?: object): void;

package/kitten/src/cli/commands/enable.d.ts

@@ -0,0 +1,9 @@
+/**
+  Kitten command-line interface (CLI): enable command.
+
+  Copyright ⓒ 2022-present, Aral Balkan
+  Small Technology Foundation
+
+  License: AGPL version 3.0.
+*/
+export default function enable(_options?: object): void;

package/kitten/src/cli/commands/logs.d.ts

@@ -0,0 +1,15 @@
+/**
+  Kitten command-line interface (CLI): logs command.
+
+  Follow Kitten systemd service logs.
+
+  Copyright ⓒ 2022-present, Aral Balkan
+  Small Technology Foundation
+
+  License: AGPL version 3.0.
+*/
+import type { SinceOption } from '../index.ts';
+/**
+  Show systemd server logs for Kitten process.
+*/
+export default function logs(options: SinceOption): void;

package/kitten/src/cli/commands/restart.d.ts

@@ -0,0 +1,11 @@
+/**
+  Kitten command-line interface (CLI): restart command.
+
+  Turn it off and then on again.
+
+  Copyright ⓒ 2024-present, Aral Balkan
+  Small Technology Foundation
+
+  License: AGPL version 3.0.
+*/
+export default function stop(_options?: object): void;

package/kitten/src/cli/commands/run.d.ts

@@ -0,0 +1,15 @@
+/**
+  Kitten command-line interface (CLI): run command.
+
+  Clones an app from a Git repository and runs it locally.
+
+  Copyright ⓒ 2024-present, Aral Balkan
+  Small Technology Foundation
+
+  License: AGPL version 3.0.
+*/
+import type { ServerOptions } from '../index.ts';
+/**
+  @param gitHttpsCloneUrl git clone url (HTTPS)
+*/
+export default function run(gitHttpsCloneUrl: string, options: ServerOptions): Promise<void>;