@small-web/kitten-types 1.1.5 → 2.0.0

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

@@ -0,0 +1,12 @@
+/**
+  Kitten types.
+
+  This entry point re-exports Kitten types for use in explicit annotations.
+
+  Side-effect: Brings `declare global { var kitten }` into scope.
+*/
+import './globals.d.ts';
+import './fragments.d.ts';
+export type { Session, WebSocket, BufferLike, slugify, Polka, KittenPolka, KittenHandler, 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';
+export type { kitten } from './globals.d.ts';

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

@@ -0,0 +1,476 @@
+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`.
+*/
+import type { Session } from '../Sessions.ts'
+export type { Session }
+
+export type { default as WebSocket, BufferLike } from '../../third-party-libraries-with-missing-type-information/ws/index.d.ts'
+export type { default as slugify } from '@sindresorhus/slugify'
+export type Polka = ReturnType<typeof polka>
+export { default as MarkdownIt } from 'markdown-it'
+
+export namespace yaml {
+  export function parse(str:string, ...args:any[]): any
+  export function stringify(value:any, ...args:any[]): string
+}
+
+/**
+  Represents an uploaded file.
+
+  @see https://kitten.small-web.org/tutorials/multipart-forms-and-file-uploads/
+*/
+export type { Upload } from '../routes/PostRoute.ts'
+
+/**
+ Abstract base class for lazily-loaded routes.
+*/
+export type { default as LazilyLoadedRoute } from '../routes/LazilyLoadedRoute.ts'
+
+import type {default as WebSocket,  BufferLike } from '../../third-party-libraries-with-missing-type-information/ws/index.d.ts'
+
+type WebSocketWithIsAlive = WebSocket & {isAlive:boolean}
+
+/**
+  MessageSender class.
+
+  Provides a namespaced send() method for use in PageSocket.
+*/
+export type { MessageSender } from '../lib/KittenPage.ts'
+
+/**
+  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 type { Listener } from '../lib/KittenComponent.ts'
+
+/**
+  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()
+    }
+  }
+*/
+import type { default as KittenComponent } from '../lib/KittenComponent.ts'
+export type { default as KittenComponent } from '../lib/KittenComponent.ts'
+
+/**
+  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`).
+*/
+import type { default as KittenPage } from '../lib/KittenPage.ts'
+export type { default as KittenPage } from '../lib/KittenPage.ts'
+
+/**
+  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).
+
+    @link https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201
+  */
+  created (body?:string):void
+
+  /**
+    Ends response with redirect via a GET request (303 See Other) to given location.
+
+    Alias: seeOther
+  */
+  get (location:string):void
+
+  /**
+    Alias for {@link get}.
+  */
+  seeOther (location:string):void
+
+  /**
+    Redirect (temporary; 307) to requested location without changing the request method.
+  */
+  redirect (location:string):void
+
+  /**
+    Alias for {@link redirect}.
+  */
+  temporaryRedirect (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
+
+  /**
+    Alias for {@link unauthenticated}.
+  */
+  unauthorised (body?:string):void
+
+  /**
+    Alias for {@link unauthenticated}.
+  */
+  unauthorized (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
+
+  /**
+    Alias for {@link error}.
+  */
+  internalServerError (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
+}
+
+/**
+  The signature of Kitten route handlers and middleware.
+
+  Like polka’s own `Middleware` type but with Kitten’s request and response
+  objects (Kitten’s middleware mixes the helper methods into every request
+  and response before any route handler runs).
+*/
+export type KittenHandler = (
+  request: KittenRequest,
+  response: KittenResponse,
+  next: polka.NextHandler
+) => void | Promise<void>
+
+type RoutePattern = RegExp | string
+
+/**
+  The Kitten server’s polka app.
+
+  A polka instance whose handlers receive Kitten’s request and response objects.
+*/
+export interface KittenPolka extends Omit<
+  Polka,
+  'find' | 'add' | 'use' | 'all' | 'get' | 'head' | 'patch' | 'options'
+  | 'connect' | 'delete' | 'trace' | 'post' | 'put'
+  | 'wares' | 'onError' | 'onNoMatch' | 'handler'
+> {
+  handler: KittenHandler
+  find(method: string, url: string): {
+    params: Record<string, string>
+    handlers: KittenHandler[]
+  }
+  add(method: string, pattern: RoutePattern, ...handlers: KittenHandler[]): this
+  use(pattern: RoutePattern, ...handlers: (KittenPolka | KittenHandler)[]): this
+  use(...handlers: (KittenPolka | KittenHandler)[]): this
+  all(pattern: RoutePattern, ...handlers: KittenHandler[]): this
+  get(pattern: RoutePattern, ...handlers: KittenHandler[]): this
+  head(pattern: RoutePattern, ...handlers: KittenHandler[]): this
+  patch(pattern: RoutePattern, ...handlers: KittenHandler[]): this
+  options(pattern: RoutePattern, ...handlers: KittenHandler[]): this
+  connect(pattern: RoutePattern, ...handlers: KittenHandler[]): this
+  delete(pattern: RoutePattern, ...handlers: KittenHandler[]): this
+  trace(pattern: RoutePattern, ...handlers: KittenHandler[]): this
+  post(pattern: RoutePattern, ...handlers: KittenHandler[]): this
+  put(pattern: RoutePattern, ...handlers: KittenHandler[]): this
+}
+
+/**
+  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/
+*/
+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;
+}

package/kitten/third-party-libraries-with-missing-type-information/index.d.ts

@@ -0,0 +1,37 @@
+/**
+  These are third-party libraries used in Kitten that do not have static type information in their module or in the centralised @types package.
+
+  To remove type warnings at author time, they are declared here and added to `typeRoots` in jsconfig.js.
+
+  (Longer term, it would be nice to contribute type information for these libraries with the eventual goal of removing this file from the project.)
+*/
+
+// JSDB
+declare module '@small-tech/jsdb'
+
+// Middleware and helpers without bundled or @types declarations.
+declare module 'cors'
+declare module 'hsts'
+declare module 'type-is'
+declare module 'cookie'
+declare module 'uid-safe'
+declare module 'tcp-port-used'
+declare module 'serve-static'
+declare module 'connect-static-file'
+declare module 'tail-file'
+declare module 'sanitize-html'
+declare module 'simply-beautiful'
+declare module 'prismjs'
+declare module 'js-beautify'
+declare module 'path-complete-extname'
+declare module '@small-tech/attribute-parser'
+
+// Markdown-it plugins (used in src/lib/html.js)
+declare module 'markdown-it-footnote'
+declare module 'markdown-it-image-figures'
+declare module 'markdown-it-ins'
+declare module 'markdown-it-bracketed-spans'
+declare module 'markdown-it-mark'
+declare module 'markdown-it-sub'
+declare module 'markdown-it-sup'
+declare module 'markdown-it-task-checkbox'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@small-web/kitten-types",
-  "version": "1.1.5",
+  "version": "2.0.0",
   "description": "Types-only package for Kitten: declares global `kitten` namespace and exports Kitten types.",
   "types": "index.d.ts",
   "files": [
@@ -8,9 +8,7 @@
     "global.d.ts",
     "fragments.d.ts",
     "types.d.ts",
-    "polka/index.d.ts",
-    "slugify/index.d.ts",
-    "ws/index.d.ts"
+    "kitten"
   ],
   "exports": {
     ".": {
@@ -57,10 +55,23 @@
     "@types/node": ">=24"
   },
   "dependencies": {
+    "@noble/ed25519": "^1.7.5",
+    "@noble/hashes": "^1.1.5",
+    "@sindresorhus/slugify": "^2.2.1",
     "@small-tech/auto-encrypt": "^5.1.0",
     "@small-tech/auto-encrypt-localhost": "^10.0.0",
     "@types/markdown-it": "^14.1.2",
     "@types/node": ">=24",
-    "kitten-icons": "^4.1.0"
+    "@types/ws": "^8.18.1",
+    "ed25519-keygen": "^0.2.4",
+    "kitten-icons": "^4.1.0",
+    "micro-aes-gcm": "^0.3.3",
+    "polka": "^1.0.0-next.25",
+    "sade": "^1.8.1",
+    "simple-git": "^3.25.0",
+    "watcher": "^2.3.1"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
   }
 }