@small-web/kitten-types 1.1.5 → 2.0.0

package/types.d.ts

@@ -1,717 +1,10 @@
-import EventEmitter from 'node:events'
-import type polka from 'polka'
-
-/**
-  Represents a browser session.
-
-  Sessions are automatically persisted (and expired) in Kitten’s internal database.
-
-  Used by Kitten to provide automatic authentication for Small Web places.
-
-  You can also add/update arbitrary session data by adding/updating properties on this object in your routes (this object maps a session object in the `kitten._db.sessions` table in the internal database). 
-
-  You can emit events on a session in order to communicate with other browser tabs and windows that share the same session.
-
-  @example
-  export default function ({ request }) {
-    request.session.kittens ??= { count: 1 }
-
-    return kitten.html`
-      <h1>Kitten count</h1>
-      <p>${'🐱️'.repeat(request.session.kittens.count++)}</p>
-    `
-  }
-
-  @see https://kitten.small-web.org/tutorials/sessions/
-
-  @remarks
-  Do not save custom classes on request.session or JSDB will throw an error when it tries to open the internal `_db` database and cannot find your custom class to instantiate.
-
-  If you want persisted session-level custom objects, store them in your own database table in `kitten.db` keyed by `session.id`.
-*/
-export class Session extends EventEmitter {
-  id: string
-  authenticated: boolean
-  challenge: string
-  createdAt: Date
-  redirectToAfterSignIn?: string
-  hasExpired (): boolean
-}
-
-export type { default as WebSocket, BufferLike } from './ws/index.d.ts'
-export type { default as slugify } from './slugify/index.d.ts'
-export type Polka = ReturnType<typeof polka>
-export { default as MarkdownIt } from 'markdown-it'
-
-export namespace yaml {
-  export function parse(str:string, reviver?:JavaScriptFunction, options?:{}): any
-  export function stringify(value:any, replacer?:JavaScriptFunction, options?:{}): string
-}
-
-/**
-  Upload class.
-*/
-
-interface UploadConstructorParameters {
-  id: string,
-  fileName: string,
-  filePath: string,
-  mimetype: string,
-  field: string,
-  encoding: string,
-  truncated: boolean,
-  done: boolean
-}
-
-/**
-  Represents an uploaded file.
-
-  @see https://kitten.small-web.org/tutorials/multipart-forms-and-file-uploads/
-*/
-export class Upload {
-
-  // Properties.
-
-  id: string
-  fileName: string
-  filePath: string
-  mimetype: string
-  field: string
-  encoding: string
-  truncated: boolean
-  done: boolean
-
-  /**
-    @private
-    @remarks For internal use by Kitten’s automatic POST route handler
-  */
-  constructor(parameters:UploadConstructorParameters)
-
-  /**
-    The absolute resource path for accessing this upload via a GET request (content-disposition: inline).
-  */
-  resourcePath: string
-
-  /**
-    Returns the absolute download path (content-disposition: attachment).
-  */
-  downloadPath: string
-
-  /**
-    Deletes this uploaded file from the file system and also from the internal database. 
-  */
-  delete(): Promise<void>
-}
-
-type BoundHandler<T> = (this: T) => void
-type AsyncKittenHandler = (request:KittenRequest, response:KittenResponse, next:AsyncKittenHandler) => Promise<void>
-
-/**
- Abstract base class for lazily-loaded routes.
-*/
-export class LazilyLoadedRoute {
-  filePath:string
-  basePath:string
-  extension:string
-  pattern:string
-  method: 'use' | 'get'
-
-  constructor(filePath:string, basePath:string)
-  get handler():BoundHandler<LazilyLoadedRoute>&{filePath?: string}
-  lazilyLoadedhandler:AsyncKittenHandler
-}
-
-import type {default as WebSocket,  BufferLike } from './ws/index.d.ts'
-
-type WebSocketWithIsAlive = WebSocket & {isAlive:boolean}
-
-/**
-  MessageSender class.
-
-  Provides a namespaced send() method for use in PageSocket.
-*/
-export class MessageSender {
-  socket:WebSocketWithIsAlive
-  sockets: [WebSocketWithIsAlive]
-  includeSelf: boolean
-
-  constructor (parameterObject: {
-    socket: WebSocketWithIsAlive,
-    connections: [WebSocketWithIsAlive],
-    includeSelf: boolean
-  })
-
-  /**
-    Sends message either to all connections or to all connections excluding the current one (depending on value of `this.includeSelf`).
-
-    You can specify an optional swap target that intelligently wraps what you’re sending with the necessary envelope tag. This is normally rather confusing with htmx’s oob swaps, especially when inserting table rows.
-
-    See: https://htmx.org/attributes/hx-swap-oob/#using-alternate-swap-strategies
-  */
-  send (message: BufferLike, swapTarget?: {
-    before?: string,
-    after?: string,
-    asFirstChildOf?: string,
-    asLastChildOf?: string
-  }):void
-}
-
-/**
-  Kitten component class.
-*/
-
-/**
-  This type definition required due to following shenanigans:
-  https://github.com/Microsoft/TypeScript/issues/20007#issuecomment-2255964704
- */
-type JavaScriptFunction = (...args: any[]) => any
-
-/**
-  A class constructor.
-*/
-type Constructor<T> = new (...args: any[]) => T
-
-/**
-  Represents the render function of a component that is bound to component (as its `this`).
-*/
-type BoundComponentRenderFunction<T extends KittenComponent> =
-  ((...args: Parameters<T['html']>) => Promise<Awaited<ReturnType<T['html']>>>)
-  & { boundObject: T }
-
-/**
-  An EventEmitter listener with a `remove()` method for cleanup.
-*/
-export class Listener {
-  /**
-    Create EventEmitter listener.
-  */
-  constructor (target:EventEmitter, eventName:string, eventHandler:JavaScriptFunction)
-
-  /**
-    Remove this listener from its EventEmitter.
-  */
-  remove ():void
-}
-
-/**
-  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`.
-
-  The example, below, updates a persisted counter via the + and - buttons (index.page.ts).
-
-  @example
-  // Initialise the database with a persisted counter object.
-  kitten.db.counter ??= { count: 0 }
-
-  export default class CounterPage extends kitten.Page {
-    counter
-
-    constructor () {
-      super()
-      this.counter = this.addChild(new Counter())
-    }
-
-    override html () {
-      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>
-        </div>
-      `
-    }
-
-    onUpdate (data: { value: number } ) {
-      kitten.db.counter.count += data.value
-      this.update()
-    }
-  }
-*/
-export class KittenComponent {
-  /**
-    Unique ID (crypto.uuid) of this component. You can overwrite it with your own if you like.
-  */
-  id: string
-
-  /**
-    Array of child components, if any. Instead of manipulating this directly, consider using the childrenOfType() method for operating on collections of components and the childOfType() method – or storing child component references as instance variables – for individual child components.
-  */
-  _children: Array<KittenComponent>
-
-  /**
-    Listeners this component has set up. There’s no reason to manipulate this directly. When you use the addEventHandler() method, Kitten handles the setup and tear-down of listeners for you automatically to avoid memory leaks.
-  */
-  _listeners: Array<Listener>
-
-  /**
-    Is this component attached to the live component hiearchy?
-  */
-  _isAttached: boolean
-
-  /**
-    Is the page this component is on connected to its client via WebSocket?
-  */
-  _isConnected: boolean
-
-  /**
-    Reference to page this component is attached to. Undefined if the page has not yet connected to the client.
-  */
-  protected get _page(): KittenPage
-
-  /**
-    This component’s parent. Undefined if component has not been added as a child to another component or a page via the addChild() method.
-  */
-  protected get _parent(): KittenComponent
-
-  /**
-    This pages socket. Not defined as private although you should only need it for low-level stuff.
-  */
-  _socket: WebSocketWithIsAlive|undefined
-
-  /**
-    All sockets active on this page. You *really* shouldn’t need to use this for anything. Not marked private as the Kitten web app uses it to introspect the page’s socket status.
-  */
-  _sockets:Array<WebSocketWithIsAlive>|undefined
-  
-  /**
-    Constructor. Good place to set initial state, including instantiating child components.
-  */
-  constructor ()
-
-  /**
-    Returns a bound version of the render function. Use when adding a child component to your `kitten.html`.
-  */
-  get component(): BoundComponentRenderFunction<this>
-
-  /**
-    Required hook: override this method with your own render function
-    that returns `kitten.html`.
-  */
-  html(parameterObject?: Record<string, any>):(string|Array<string>|Promise<string|Array<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.
-  */
-  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: {
-    page?: KittenComponent,
-    request?: KittenRequest,
-    response?: KittenResponse
-  }):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: {
-    page?: KittenComponent,
-    request?: KittenRequest,
-    response?: KittenResponse
-  }):void
-
-  /**
-    Adds child component to this one.
-
-    Child components are entered into the event bubbling hierarchy and contain a reference to the page that they’re on.
-  */
-  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 event handler for an EventEmitter.
-
-    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: object, eventName: string, eventHandler: JavaScriptFunction):void
-
-  /**
-    Helper for sending an updated version of this component to the page.
-  */
-  update ():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
-
-  /**
-    Emits an event that is bubbled to all of its children.
-
-    This is a good way, for example, to set a specific state on a page or component, where each child component knows what it should look like in that state.
-
-    The event name → event handler naming convention mapping works exactly like it does with events received from the client.
-
-    @param {string} eventName
-    @param {any} data
-    @param {any} event
-    @param {string} target - if provided, and is prefixed by this component’s Kitten ID, we only bubble to the target and its children.
-    @param {any} self - if provided is used to bypass target check for object doing the bubbling.
-  */
-  emit (eventName:string, data?:any, event?:any, target?:string, self?:any):void
-
-  /**
-    Helper for adding an event handler for a page event and streaming an updated version of the component to the client (a common pattern).
-
-    @param {string} eventName
-  */
-  updateOnEvent (eventName:string):void
-
-  /**
-    Helper (handler) for sending an updated version of this component to the page.
-  */
-  sendUpdatedComponentToPage ():void
-}
-
-/**
-  KittenPage class.
-
-  A KittenPage is a specialised KittenComponent that represents a live page in memory (a live page is one that has an automatic WebSocket connection to the page rendered by the PageRoute).
-
-  A KittenPage constitutes the root of the server-side component hierarchy.
-
-  Instance data in a `KittenPage` instance sticks around for the lifetime of the page (e.g., until a reload or a navigation event away from it in the browser).
-
-  If you need greater persistence, use session storage (`request.session`) or the built-in JSDB database (`kitten.db`).
-*/
-export class KittenPage extends KittenComponent {
-  request: KittenRequest
-  response: KittenResponse
-  session: Session
-  socket: WebSocketWithIsAlive
-  sockets: [WebSocketWithIsAlive]
-  data: Record<string, any>
-  everyone: MessageSender
-  everyoneElse: MessageSender
-
-  /**
-    Construct new KittenPage instance.
-
-    Note that the `request` and `response` properties are set after construction by Kitten to keep the constructor easy to override in your own subclasses. (The constructor is a good place to initialise known child components, etc.)
-
-    Every page has a unique ID (inherited from KittenComponent) and can hold ephemeral page-level instance data. e.g., child components. (Page storage is ephemeral is that it only lasts for the lifetime of a page in the browser and is destroyed when the page is closed or reloaded.)
-
-    If you need greater persistence, please use session storage (request.session) or the built-in JavaScript Database (JSDB) that you can reference at `kitten.db`.
-
-    A page is known as an “authored page” if the author of the Kitten app/site wrote and exported a KittenPage subclass in the route (as opposed to exporting a simple function and function-based event handlers that then resulted in a generic page being created by Kitten’s `PageRoute` class). Keeping track of this is an optimisation that enables the `PageSocketRoute` to not have to import the source file again if the page was authored as a page instance and thus already contains its event handlers (as opposed to the event handlers being exported as separate functions that have be read in and mixed into the generic `KittenPage` instance by the `PageSocketRoute`).
-  */
-  constructor()
-  
-  /**
-    The page has connected to its WebSocket. The list of sockets and the specific socket for this page are passed for storage on the page and the list of event handlers imported from the page (when using function-based page routes), if any, to be mixed into this instance as methods.
-  */
-  connect (socket: WebSocketWithIsAlive, sockets: [WebSocketWithIsAlive], eventHandlers: Record<string, JavaScriptFunction>):void
-
-  /**
-    Dynamically add specified event handler for specified event name.
-
-    @deprecated Instead of `on(eventName, handler)`, export `onEventName()` from your page (or add `onEventName()` method to your `kitten.Page` subclass if using class-based page routes.)
-  */
-  on (eventName: string, eventHandler: (data: any) => void):void
-
-  /**
-    Send specified message to just this page’s socket.
-
-    You can specify an optional swap target that intelligently wraps what you’re sending with the necessary envelope tag. This is normally rather confusing with htmx’s oob swaps, especially when inserting table rows. See: https://htmx.org/attributes/hx-swap-oob/#using-alternate-swap-strategies
-  */
-  send (message: BufferLike|Promise<BufferLike>, swapTarget?: {
-    before?: string,
-    after?: string,
-    asFirstChildOf?: string,
-    asLastChildOf?: string
-  }):void
-}
-
-/**
-  Request and response types.
-
-  These vary per route type but are all built on the base of Polka’s request and response objects which are, themselves, based on the incoming message and server response types of Node’s own http module.
-*/
-
-import type { IncomingMessage, ServerResponse } from 'http'
-
-export interface ParsedURL {
-	pathname: string
-	search: string
-	query: Record<string, string | string[]> | void
-	raw: string
-}
-
-export type PolkaResponse = ServerResponse
-
-export interface PolkaRequest extends IncomingMessage {
-	url: string
-	method: string
-	originalUrl: string
-	params: Record<string, string>
-	path: string
-	search: string
-	query: Record<string,string>
-	body?: any
-	_decoded?: true
-	_parsedUrl: ParsedURL
-}
-
-/**
-  The request objects received by Kitten routes.
-
-  Based on Polka’s request object with extra Kitten-specific properties and methods.
-*/
-export interface KittenRequest extends PolkaRequest {
-  /**
-    The raw body of non-multipart requests. Used, for example, for validation webhook signatures.
-  */
-  rawBody: Buffer
-
-  /**
-    Check if the incoming request contains the `"Content-Type"` header field, and, if so, if it contains the specified mime `type`.
-
-    Examples:
-
-      // With Content-Type: text/html; charset=utf-8
-      req.is('html');
-      req.is('text/html');
-      req.is('text/*');
-      // => true
-
-      // When Content-Type is application/json
-      req.is('json');
-      req.is('application/json');
-      req.is('application/*');
-      // => true
-      req.is('html');
-      // => false
-
-    @link https://github.com/expressjs/express/blob/master/lib/request.js#L231
-  */
-  is (types:Array<string>|string):string|false|null
-
-  /**
-    Represents a browser session.
-
-    Sessions are automatically persisted (and expired) in Kitten’s internal database.
-
-    Used by Kitten to provide automatic authentication for Small Web places.
-
-    You can also add/update arbitrary session data by adding/updating properties on this object in your routes (this object maps a session object in the `kitten._db.sessions` table in the internal database). 
-
-    You can emit events on a session in order to communicate with other browser tabs and windows that share the same session.
-
-    @example
-    export default function ({ request }) {
-      request.session.kittens ??= { count: 1 }
-
-      return kitten.html`
-        <h1>Kitten count</h1>
-        <p>${'🐱️'.repeat(request.session.kittens.count++)}</p>
-      `
-    }
-
-    @see https://kitten.small-web.org/tutorials/sessions/
-
-    @remarks
-    Do not save custom classes on request.session or JSDB will throw an error when it tries to open the internal `_db` database and cannot find your custom class to instantiate.
-
-    If you want persisted session-level custom objects, store them in your own database table in `kitten.db` keyed by `session.id`.
-  */
-  session: Session & {
-    [key: string]: any
-  }
-}
-
-type TypedArray = Int8Array|Uint8Array|Uint8ClampedArray|Int16Array|Uint16Array|Int32Array|Uint32Array|Float32Array|Float64Array|BigInt64Array|BigUint64Array
-
 /**
-  The response objects received by Kitten routes.
-
-  Based on Polka’s response object with extra Kitten-specific properties and methods.
-*/
-export interface KittenResponse extends PolkaResponse {
-  /**
-    JSON.stringifies passed data and ends response with inline JSON using proper headers.
-  */
-  json (data:any):void
-
-  /**
-    JSON.stringifies passed data and ends response with JSON attachment using proper headers and requested file name (or data.json as fallback if no file name is provided).
-  */
-  jsonFile (data:any, fileName?:string):void
-
-  /**
-    Ends response with a file. Optionally, uses passed file name (or `'download'` as fallback) and passed mime type (or `'application/octet-stream'` as fallback).
-  */
-  file (data:string|Buffer|TypedArray|DataView, fileName?:string, mimeType?:string):void
-
-  /**
-    Ends response with 200 OK response code, and the response body, if any (and `''` if not).
-
-    @link https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200
-  */
-  ok (body?:string):void
-  
-  /**
-    Ends response with 201 Created response code, and the response body, if any (and `''` if not).
+  Kitten Types (@small-web/kitten-types)
 
-    @link https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201
-  */
-  created (body?:string):void
+  Reusable Kitten types for explicit annotations.
 
-  /**
-    Ends response with redirect via a GET request (303 See Other) to given location.
-
-    Alias: seeOther
-  */
-  get (location:string):void
-
-  /**
-    Redirect (temporary; 307) to requested location without changing the request method.
-  */
-  redirect (location:string):void
-
-  /**
-    Redirect (permanentl 308) to requested location without changing the request method.
-  */
-  permanentRedirect (location:string):void
-
-  /**
-    400 Bad Request
-
-    Indicates that the server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
-
-    @link https://httpwg.org/specs/rfc9110.html#rfc.section.15.5.1
-  */
-  badRequest (body?:string):void
-
-  /**
-    “401 Unauthorized” (actually, unauthenticated) response.
-
-    Aliases: unauthorised, unauthorized.
-  */
-  unauthenticated (body?:string):void
-
-  /**
-    403 Forbidden response. This should be returned if the request is authenticated but lacks the authorisation (i.e., sufficient rights) to access the resource.
-
-    If the request requires authentication but has not been authenticated, you should return a “401 Unauthorized” (actually: unauthenticated) response.
-
-    @see unauthenticated
-  */
-  forbidden (body?:string):void
-
-  /**
-    404 Not Found response.
-  */
-  notFound (body?:string):void
-
-  /**
-    500 Internal Server Error response.
-
-    Alias: internalServerError.
-  */
-  error (body?:string):void
-
-  /**
-    General shorthand helper for setting the status code and ending the response with an optional body.
-  */
-  withCode (statusCode:number, body?:string):void
-}
-
-/**
-  Kitten’s POST request object.
-
-  If the POST route had a multi-part form with file uploads, they will be handled automatically by Kitten and you can find them in the `uploads` property.
-
-  @see https://kitten.small-web.org/tutorials/multipart-forms-and-file-uploads/
+  Generated from Kitten’s TypeScript source code
+  (see kitten/ – regenerated via `npm run sync-types` in the Kitten repository).
 */
-export interface KittenPostRequest extends KittenRequest {
-  uploads: Upload[]
-}
-
-/* Crypto */
-
-type Hex = Uint8Array | string;
-type PrivKey = Hex | bigint | number;
-
-export class Point {
-  readonly x: bigint;
-  readonly y: bigint;
-  static BASE: Point;
-  static ZERO: Point;
-  _WINDOW_SIZE?: number;
-  constructor(x: bigint, y: bigint);
-  _setWindowSize(windowSize: number): void;
-  static fromHex(hex: Hex, strict?: boolean): Point;
-  static fromPrivateKey(privateKey: PrivKey): Promise<Point>;
-  toRawBytes(): Uint8Array;
-  toHex(): string;
-  toX25519(): Uint8Array;
-  isTorsionFree(): boolean;
-  equals(other: Point): boolean;
-  negate(): Point;
-  add(other: Point): Point;
-  subtract(other: Point): Point;
-  multiply(scalar: number | bigint): Point;
-}
 
-export class Signature {
-  readonly r: Point;
-  readonly s: bigint;
-  constructor(r: Point, s: bigint);
-  static fromHex(hex: Hex): Signature;
-  assertValidity(): this;
-  toRawBytes(): Uint8Array;
-  toHex(): string;
-}
+export type * from './kitten/src/types/types.d.ts'