@small-web/kitten-types 1.1.5 → 2.0.0

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

@@ -0,0 +1,13 @@
+/**
+  Kitten command-line interface (CLI): serve command.
+
+  Copyright ⓒ 2021-present, Aral Balkan
+  Small Technology Foundation
+
+  License: AGPL version 3.0.
+*/
+import type { ServerOptions } from '../index.ts';
+/**
+  Start Kitten server instance.
+*/
+export default function serve(pathToServe: string | undefined, options: ServerOptions): Promise<void>;

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

@@ -0,0 +1 @@
+export default function shell(): void;

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

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

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

@@ -0,0 +1,15 @@
+/**
+  Kitten command-line interface (CLI): status command.
+
+  Display Kitten systemd service status.
+
+  Copyright ⓒ 2022-present, Aral Balkan
+  Small Technology Foundation
+
+  License: AGPL version 3.0.
+*/
+/**
+  Display error in console and reject promise.
+*/
+export declare function rejectWithError(message: string, reject: (reason?: any) => void): void;
+export default function status(_options?: object): Promise<unknown>;

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

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

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

@@ -0,0 +1,9 @@
+/**
+  Kitten command-line interface (CLI): uninstall command.
+
+  Copyright ⓒ 2021-present, Aral Balkan
+  Small Technology Foundation
+
+  License: AGPL version 3.0.
+*/
+export default function uninstall(): Promise<void>;

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

@@ -0,0 +1,7 @@
+import type { ServerOptions } from '../index.ts';
+/**
+  Update the Kitten package.
+*/
+export default function (options: ServerOptions & {
+    'api-version'?: number;
+}): Promise<void>;

package/kitten/src/cli/index.d.ts

@@ -0,0 +1,55 @@
+/**
+  Kitten Command Line Interface (CLI).
+
+  Copyright © 2022-present Aral Balkan, Small Technology Foundation.
+  Licensed under GNU AGPL version 3.0.
+*/
+import sade from 'sade';
+export declare const COMMANDS: string[];
+export declare const COMMANDS_AND_ALIASES: string[];
+declare const OPTION_DOMAIN = "domain";
+declare const OPTION_ALIASES = "aliases";
+declare const OPTION_PORT = "port";
+declare const OPTION_OPEN = "open";
+declare const OPTION_WORKING_DIRECTORY = "working-directory";
+declare const OPTION_DOMAIN_TOKEN = "domain-token";
+declare const OPTION_SMALL_WEB_HOST_DOMAIN = "small-web-host-domain";
+declare const OPTION_SINCE = "since";
+declare const OPTION_ALL = "all";
+export type WorkingDirectoryOption = {
+    [OPTION_WORKING_DIRECTORY]: string;
+};
+export type DomainAndAliasesOptions = {
+    [OPTION_DOMAIN]?: string;
+    [OPTION_ALIASES]?: string;
+};
+export type DomainTokenOption = {
+    [OPTION_DOMAIN_TOKEN]?: string;
+};
+export type SmallWebHostDomainOption = {
+    [OPTION_SMALL_WEB_HOST_DOMAIN]?: string;
+};
+export type PortOption = {
+    [OPTION_PORT]?: number;
+};
+export type OpenOption = {
+    [OPTION_OPEN]?: boolean;
+};
+export type SinceOption = {
+    [OPTION_SINCE]: string;
+};
+export type AllOption = {
+    [OPTION_ALL]: boolean;
+};
+export type ServerOptions = WorkingDirectoryOption & DomainAndAliasesOptions & PortOption & OpenOption;
+export type DeploymentOptions = DomainAndAliasesOptions & DomainTokenOption & SmallWebHostDomainOption;
+export type TailOptions = ServerOptions & AllOption;
+export default class CommandLineInterface {
+    commands: ReturnType<typeof sade>;
+    constructor();
+    /**
+      Parse process arguments.
+    */
+    parse(): Promise<void>;
+}
+export {};

package/kitten/src/cli/lib/WarningBox.d.ts

@@ -0,0 +1,8 @@
+export default class WarningBox {
+    lines: string[];
+    constructor();
+    line(line: string): void;
+    emptyLine(): void;
+    render(): string;
+    print(): void;
+}

package/kitten/src/cli/lib/header.d.ts

@@ -0,0 +1,10 @@
+/**
+  Kitten Command Line Interface (CLI) header.
+
+  Copyright © 2022-present Aral Balkan, Small Technology Foundation.
+  Licensed under GNU AGPL version 3.0.
+*/
+/**
+  Display command-line interface header.
+*/
+export default function header(): void;

package/kitten/src/components/SvgSpinner.component.d.ts

@@ -0,0 +1,9 @@
+/**
+  SVG spinner component.
+
+  Spinner SVG courtesy of https://github.com/n3r4zzurr0/svg-spinners/blob/main/svg-css/bars-rotate-fade.svg?short_path=a639ef3
+*/
+declare const _default: ({ small }: {
+    small?: boolean | undefined;
+}) => string | string[] | Promise<string | string[]>;
+export default _default;

package/kitten/src/lib/KittenComponent.d.ts

@@ -0,0 +1,340 @@
+/**
+  Kitten Component.
+  
+  A class that makes it easier to author hierarchies of connected components.
+
+  Handles wiring up and disposal of event listeners for you and gives you an
+  ergonomic, class-based way of writing maintainable applications that take
+  advantage of Kitten’s Streaming HTML workflow while working with well-encapsulated,
+  self-contained components in a clear hierarchy.
+
+  Extend and instantiate this class to create your own components (components, fragments,
+  layout components, and pages) and provide at least an override for the `html()` method,
+  which is just a function that returns `kitten.html`.
+
+  @example
+
+  // index.page.ts
+  //
+  // Updates a persisted counter via + and - buttons.
+  //
+  // Make sure you `npm install --save-dev @small-web/kitten types` to load the type information for the global `kitten` object.
+
+  // Initialise the database with a persisted counter object.
+  kitten.db.counter ??= { count: 0 }
+
+  export default class CounterPage extends kitten.Page {
+    // Counter is strongly typed via inference (see constructor).
+    counter
+
+    // The constructor is where we initialise state, including setting up any child components we want available at initial render.
+    constructor () {
+      super()
+      this.counter = this.addChild(new Counter())
+    }
+
+    override html () {
+      // While this.counter is a reference to the Counter KittenComponent, and not it’s render function, Kitten knows to use its `component` property to get a reference to its render function while rendering it. If you want to be explicit about it (e.g., to visually differentiate stateful components from stateless ones in your kitten.html), you can write `<${this.counter.component}` manually, but it’s not necessary.
+      return kitten.html`
+        <page css>
+        <h1>Counter</h1>
+        <${this.counter} />
+      `
+    }
+  }
+
+  class Counter extends kitten.Component {
+    override html () {
+      return kitten.html`
+        <div>
+          <div
+            id='count'
+            aria-live='assertive'
+          >
+            ${kitten.db.counter.count}
+          </div>
+          <button name='update' connect data='{value: -1}' aria-label='decrement'>-</button>
+          <button name='update' connect data='{value: 1}' aria-label='increment'>+</button>
+          <style inline>
+            @scope {
+              div {
+                font-size: 3em;
+                margin: 0.25em 0;
+              }
+            }
+          </style>
+        </div>
+      `
+    }
+
+    onUpdate (data: { value: number } ) {
+      kitten.db.counter.count += data.value
+      this.update()
+    }
+  }
+*/
+import type KittenPage from './KittenPage.ts';
+import type { KittenPageEvent } from './KittenPage.ts';
+import EventEmitter from 'node:events';
+/**
+  Type definitions. First one required due to following shenanigans:
+  https://github.com/Microsoft/TypeScript/issues/20007#issuecomment-2255964704
+ */
+export type JavaScriptFunction = (...args: any[]) => any;
+type Constructor<T> = new (...args: any[]) => T;
+type BoundComponentRenderFunction<T extends KittenComponent> = ((...args: Parameters<T['html']>) => Promise<Awaited<ReturnType<T['html']>>>) & {
+    boundObject: T;
+};
+export declare class Listener {
+    target: EventEmitter<[never]>;
+    eventName: string;
+    eventHandler: JavaScriptFunction;
+    /**
+      Create EventEmitter listener.
+    */
+    constructor(target: EventEmitter, eventName: string, eventHandler: JavaScriptFunction);
+    remove(): void;
+}
+export default class KittenComponent extends EventEmitter {
+    #private;
+    id: string;
+    _listeners: Array<Listener>;
+    _children: Array<KittenComponent>;
+    _isAttached: boolean;
+    _isConnected: boolean;
+    /**
+      Override the constructor to initialise child components and save initial component state.
+  
+      Remember to call super() before anything else.
+    */
+    constructor();
+    /**
+      Overridable (hook) methods.
+  
+      Required:
+  
+      - html()            - render function; outputs kitten.html. May be synchronous or asynchronous.
+  
+      Optional:
+  
+      - onConnect()       - called when the page this component is on (or is) connects.
+  
+      - onDisconnect()    - called when the page this component is on (or is) disconnects.
+  
+      - onAddToParent() - called when component is added to parent (page might not be connected yet).
+    */
+    /**
+      Override this function with your own function that returns kitten.html.
+    */
+    html({ ...props }?: {}): string | string[] | Promise<string | string[]>;
+    /**
+      Optional hook: override this method to run custom logic when the component has been added to the component hierarchy via addChild() (attached to its parent and, thus, to the component hiearchy).
+  
+      At this point it will have a reference to its parent component, the page it’s on, and to any instance data that it might have, (at `this._parent`, `this._page`, and `this.`, respectively.)
+  
+      However, there is no guarantee that the page this component is attached to has connected to the client via its automatic WebSocket. For that, rely on the
+      `onConnect()` handler instead.
+  
+      TODO: Is there any need to keep this around?
+    */
+    onAddToParent(): void;
+    /**
+      Optional hook: override this method to provide custom logic for your app to be run when the page this component is on connects to the client via its WebSocket.
+  
+      This hook will get called not just for initially-rendered components when the page first connects but also for any components dynamically added to an already-connected page/component hierarchy after the fact.
+  
+      (So you can be sure that this handler will be called once when a component is fully initialised on a connected page. This is a good place to add event handlers or to start streaming updates to the client.)
+    */
+    onConnect(_parameterObject?: {}): void;
+    /**
+      Optional hook: override this method to run custom logic when the page this component is on disconnects from the client via its WebSocket. (This usually means the page the about to be unloaded, either because the person is nagivating away from it or reloading it.)
+    */
+    onDisconnect(_parameterObject?: {}): void;
+    /**
+      Returns a bound version of the render function that can be used in Kitten HTML templates.
+  
+      It’s always async so mixed sync/async component hierarchies in Kitten HTML are uniformly awaitable (the renderer relies on the wrapper’s AsyncFunction identity and on boundObject).
+    */
+    get component(): BoundComponentRenderFunction<this>;
+    /**
+      Reference to the page this component is attached to.
+  
+      You should ideally not use this. Instead dispatch an event from your component that your page can react to.
+    */
+    get _page(): KittenPage;
+    set _page(page: KittenPage);
+    /**
+      Reference to the parent component this component is attached to.
+  
+      You should ideally not use this. Instead dispatch an event from your component that your parent can listen for and react to.
+    */
+    get _parent(): KittenComponent;
+    set _parent(parent: KittenComponent);
+    /**
+  
+      Adds child component to this one and returns a reference to it.
+  
+      Canonical usage:
+  
+      this.childComponent = this.addChild(new ChildComponent(some, instance, props))
+  
+      Child components are entered into the event bubbling hierarchy and contain a reference to the page that they’re on.
+  
+      Note: the page the component is added to might not have connected yet.
+    */
+    addChild<T extends KittenComponent>(component: T): T;
+    /**
+      Removes a child and returns a reference to it.
+  
+      If child cannot be found, returns null.
+  
+      Usually called by the child itself when it is being removed.
+    */
+    removeChild<T extends KittenComponent>(component: T): T | null;
+    /**
+      Gets all components of a given type (useful when you have collections of child components that you want to render, say, in a list).
+    */
+    childrenOfType<T extends KittenComponent>(type: Constructor<T>): T[];
+    /**
+      Returns the first child component encountered of type T. Use when you know there is only one child of type T and you don’t want to a reference to it in your KittenComponent subclass.
+  
+      Returns undefined if a child of type T cannot be found.
+    */
+    childOfType<T extends KittenComponent>(type: Constructor<T>): T | undefined;
+    /**
+      Add an event handler. Event listening and listener clean-up
+      are automatically handled so the author doesn’t have to worry
+      about implementing this finickety aspect manually.
+    */
+    addEventHandler(target: EventEmitter, eventName: string, eventHandler: (this: this, ...args: any[]) => any): void;
+    /**
+      Helper: emits page-wide event on the page this component is on.
+    */
+    emitPageEvent(eventName: string, ...args: any): void;
+    /**
+      Helper: emits session-wide event on the session this page belongs to.
+    */
+    emitSessionEvent(eventName: string, ...args: any): void;
+    /**
+      Helper: emits global event on kitten.events.
+    */
+    emitGlobalEvent(eventName: string, ...args: any): void;
+    /**
+      A helper for adding an event handler and streaming an updated
+      version of the computer to the client.
+    */
+    updateOnEvent(eventName: string): void;
+    /**
+      Helper for sending an updated version of this component to the page.
+  
+      Also handles removal of event listeners for itself and all its
+      children so we don’t have any leaks.
+    */
+    update(): Promise<void>;
+    /**
+      Helper for removing this component from the live component hierachy.
+  
+      Also handles removal of event listeners for itself and all its children so we don’t have any leaks.
+    */
+    remove(): void;
+    /**
+      Routes an event to the correct component by ID by recursively visiting descendants.
+    */
+    _routeEvent(kittenPageEvent: KittenPageEvent): boolean;
+    _callEventHandler(kittenPageEvent: KittenPageEvent): void;
+    /**
+      The internal onConnect handler that gets called by Kitten.
+      We use this to connect event handlers, listen for events,
+      and inform connected components to do the same.
+    */
+    _onConnect(page: KittenPage): void;
+    /**
+      The internal onDisconnect handler that gets called by Kitten.
+      We use this to remove event listeners and and inform connected
+      components to do the same.
+    */
+    _onDisconnect(page: KittenPage): void;
+    /**
+      Introspection API.
+  
+      These properties help authors debug their running apps using the Kitten Shell (REPL)
+    */
+    /**
+      Displays component hierarchy, methods, and properties of the current component.
+    */
+    $info(): void;
+    /**
+      Returns the “name” of this page: i.e., it’s class name.
+    */
+    get $name(): string;
+    /**
+      Returns all properties on this component.
+    */
+    get $properties(): string[];
+    /**
+      The names of this component’s “public” properties.
+  
+      We use “public” very loosely to mean any property not starting with an underscore (to keep the display clean of internal properties).
+    */
+    get $publicProperties(): string[];
+    /**
+      The names of this component’s “internal” properties.
+  
+      We use “internal” very loosely to mean any property starting with an underscore (to keep the display clean of internal properties).
+    */
+    get $internalProperties(): string[];
+    /**
+      The methods of this component.
+    */
+    get $methods(): string[];
+    /**
+      Returns the index and names of the child components of this component.
+    */
+    get $children(): string[];
+    /**
+      Returns a pretty representation of the rough size.
+    */
+    get $size(): string;
+    /**
+      Helper: returns a byte value in pretty, human-friendly terms.
+    */
+    ___prettyBytes(bytes: number, decimalPlaces?: number): string;
+    /**
+      Returns the rough size of this object in bytes.
+    */
+    get ___size(): number;
+    /**
+      Returns a recursive tree view of this component and its descendents.
+    */
+    $tree(): string;
+    /**
+      (Internal) Returns the short ID for this component.
+  
+      The short ID is the first fragment of the UUID. This has 32bits of entropy which should be adequate for this use case.
+  
+      (The 50% collision threshold via the birthday problem formula – https://en.wikipedia.org/wiki/Birthday_problem – is ~77,163 components and at 1,000 components there is a 0.01% chance of collisions. At 100 components, the risk is 0%. If you have 1,000+ components on your page, you have bigger issues to worry about.)
+    */
+    get ___shortId(): string;
+    /**
+      (Internal) Transform [class X extends Y] to X (Y)
+    */
+    ___prettyName({ isTitle, reverse }?: {
+        isTitle?: boolean | undefined;
+        reverse?: boolean | undefined;
+    }): string;
+    /**
+      Returns a reference to the component (in this component’s entire component tree) with the passed short ID, or undefined if not found.
+  
+      @param shortId - The first fragment of this component’s UUID, as shown in the output of the __tree() method.
+    */
+    $componentWithId(shortId: string): KittenComponent | undefined;
+    /**
+      Returns a flattened array of all the children of the component hierarchy starting at this component (recursive).
+    */
+    ___allChildrenFlattened(): Array<KittenComponent>;
+    /**
+      (Internal) Recursive tree view.
+    */
+    ___tree(prefix?: string): string;
+}
+export {};

package/kitten/src/lib/KittenMoji.d.ts

@@ -0,0 +1,35 @@
+/**
+  KittenMoji
+
+  Emoji map and methods used to Base256 encode a person’s ed25519
+  private key. Emoji is chosen on purpose to make it impossible
+  for the person to type it in, thereby necessitating the use of
+  copy and paste and a password manager (and hence good security
+  hygiene).
+
+  The emoji chosen for the Base256 alphabet are mainly from the
+  animals and plants and food groups with some exceptions (to
+  avoid common phobias or triggers, etc., and because there are
+  just some that have special meaning for me or that I like.) – Aral ;)
+
+  All emoji in this list are surrogate pairs without any
+  special modifiers.
+
+  The KittenMoji standard is being frozen in time on Friday,
+  November 25th, 2022 and the string created by joining the
+  array has the following sha256 hash:
+
+  d9b1533de36a75c9e47f1713aada4ff332918ff0d3cada5b645ca84d73dd50d6
+
+  ⚠️ Node-native subgraph: this module is loaded natively by Node.js via
+  type stripping. Only use erasable TypeScript syntax here. It is also
+  bundled for the browser (via crypto.ts), so it must remain platform-neutral.
+*/
+/**
+  Convert secret bytes to emoji string.
+*/
+export declare function secretToEmojiString(secret: Uint8Array): string;
+/**
+  Convert emoji string to secret bytes.
+*/
+export declare function emojiStringToSecret(emojiString: string): Uint8Array;

package/kitten/src/lib/KittenPackage.d.ts

@@ -0,0 +1,56 @@
+/**
+  Kitten Package.
+*/
+import Version from './Version.ts';
+export type RemoteVersionDetails = {
+    versionStamp: number;
+    gitHash: string;
+    apiVersion: number;
+    nodeVersion: string;
+    exactVersion: string;
+    buildDate: Date;
+    releaseDate: Date;
+    _buildDate: string;
+    _releaseDate: string;
+    upload: import('../types/index.ts').Upload;
+};
+/**
+  Represents the currently-installed Kitten package.
+
+  Provides information about and manages updates of the
+  package by communicating with Kitten’s deployment site
+  (https://kittens.small-web.org).
+
+  _Note that this class does NOT manage automatic updates.
+  For that, please see the AutomaticUpdates class._
+*/
+export default class KittenPackage {
+    static instance: KittenPackage;
+    currentVersion: Version;
+    apiVersion: number;
+    limitByApiVersion: boolean;
+    versionCheckUrl: string;
+    latestVersion: RemoteVersionDetails | undefined;
+    compatibleVersion: RemoteVersionDetails | undefined;
+    latestRecommendedVersion: RemoteVersionDetails | undefined;
+    static getInstance(): KittenPackage;
+    constructor();
+    get hasCompatibleVersion(): boolean;
+    get isLatestReleaseVersion(): boolean;
+    get isMoreRecentThanReleaseVersion(): boolean;
+    get canBeUpgraded(): boolean;
+    /**
+      Upgrades the Kitten package to the latest recommended version.
+  
+      Note that if you’re running a development version, this will actually result
+      in a downgrade to the latest available published package. Make sure your
+      interface detects this state and prompts before downgrading.
+  
+      @throws
+    */
+    upgrade(apiVersion?: number): void;
+    /**
+      Fetches the latest version information from kittens.small-web.org.
+    */
+    update(): Promise<void>;
+}