@small-web/kitten-types 1.0.0 → 1.0.2

package/index.d.ts

@@ -1,14 +1,11 @@
-// @small-web/kitten-types
-//
-// Types-only package for Kitten (https://kitten.small-web.org).
-//
-// This entry point re-exports the reusable Kitten types (for explicit
-// annotations) and pulls in the ambient `declare global` declaration of the
-// `kitten` namespace (so that the global `kitten` object is typed wherever
-// this package is on the type-checker’s include path).
+/**
+  Kitten Types (@small-web/kitten-types)
+
+  This entry point re-exports Kitten types for use in explicit annotations.
+
+  Side-effect: Brings `declare global { var kitten }` into scope for any project that depends on this package.
+*/
 
-// Side-effect import: brings the ambient `declare global { var kitten }` into
-// scope for any project that depends on this package.
 import './global.d.ts'
 
 // Reusable types, re-exported for explicit annotations
@@ -38,6 +35,5 @@ export type {
 
 export { yaml } from './types.d.ts'
 
-// Also export the hand-written global namespace shape, in case a consumer
-// wants to reference it explicitly (e.g. `typeof kitten`).
-export type { KittenGlobal } from './global.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'

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@small-web/kitten-types",
-  "version": "1.0.0",
-  "description": "Types-only package for Kitten: declares the global `kitten` namespace and exports Kitten types.",
+  "version": "1.0.2",
+  "description": "Types-only package for Kitten: declares global `kitten` namespace and exports Kitten types.",
   "types": "index.d.ts",
   "exports": {
     ".": {

package/types.d.ts

@@ -1,5 +1,34 @@
 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
@@ -11,7 +40,7 @@ export class Session extends EventEmitter {
 
 export type { default as WebSocket, BufferLike } from './ws/index.d.ts'
 export type { default as slugify } from './slugify/index.d.ts'
-export type { default as Polka } from './polka/index.d.ts'
+export type Polka = ReturnType<typeof polka>
 export { default as MarkdownIt } from 'markdown-it'
 
 export namespace yaml {
@@ -34,10 +63,31 @@ interface UploadConstructorParameters {
   done: boolean
 }
 
+/**
+  Represents an uploaded file.
+
+  @see https://kitten.small-web.org/tutorials/multipart-forms-and-file-uploads/
+*/
 export class Upload {
+  /**
+    @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>
 }
 
@@ -104,12 +154,21 @@ export class MessageSender {
  */
 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.
@@ -122,6 +181,60 @@ export class Listener {
   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.
@@ -195,16 +308,11 @@ export class KittenComponent {
   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.
+    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.
+    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.)
+    (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,
@@ -213,10 +321,7 @@ export class KittenComponent {
   }):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.)
+    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,
@@ -227,8 +332,7 @@ export class KittenComponent {
   /**
     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.
+    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
 
@@ -256,9 +360,7 @@ export class KittenComponent {
   /**
     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.
+    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
 
@@ -270,8 +372,7 @@ export class KittenComponent {
   /**
     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.
+    Also handles removal of event listeners for itself and all its children so we don’t have any leaks.
   */
   remove ():void
 
@@ -291,16 +392,14 @@ export class KittenComponent {
   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).
+    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.
+    Helper (handler) for sending an updated version of this component to the page.
   */
   sendUpdatedComponentToPage ():void
 }
@@ -308,13 +407,13 @@ export class KittenComponent {
 /**
   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). It constitutes the root of the
-  server-side component hierarchy. Its `html()` method is dynamically bound
-  by the PageRoute to the authored page route function in function-based authoring
-  and it is used directly via its global `kitten.Page` reference when authoring
-  class-based page routes.
+  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
@@ -327,35 +426,20 @@ export class KittenPage extends KittenComponent {
   everyoneElse: MessageSender
 
   /**
-    Construct new KittenPage instance with a reference to the
-    request and response objects for the page.
+    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 data. e.g., the states of components when
-    using the Streaming HTML workfow. (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.)
+    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, use session storage (request.session) or
-    the built-in JSDB database (kitten.db).
+    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 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 enabled 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).
+    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.
+    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
 
@@ -369,11 +453,7 @@ export class KittenPage extends KittenComponent {
   /**
     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
+    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,
@@ -386,10 +466,7 @@ export class KittenPage extends KittenComponent {
 /**
   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.
+  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'
@@ -416,6 +493,11 @@ export interface PolkaRequest extends IncomingMessage {
 	_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.
@@ -423,8 +505,7 @@ export interface KittenRequest extends PolkaRequest {
   rawBody: Buffer
 
   /**
-    Check if the incoming request contains the "Content-Type"
-    header field, and it contains the given mime `type`.
+    Check if the incoming request contains the `"Content-Type"` header field, and, if so, if it contains the specified mime `type`.
 
     Examples:
 
@@ -446,43 +527,71 @@ export interface KittenRequest extends PolkaRequest {
   */
   is (types:Array<string>|string):string|false|null
 
-  session: Session
+  /**
+    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.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).
+    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 'dowload' as fallback) and passed mime type (or
-    'application/octet-stream' as fallback).
+    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).
+    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).
+    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
   */
@@ -508,9 +617,7 @@ export interface KittenResponse extends PolkaResponse {
   /**
     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).
+    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
   */
@@ -524,13 +631,9 @@ export interface KittenResponse extends PolkaResponse {
   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.
+    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.
+    If the request requires authentication but has not been authenticated, you should return a “401 Unauthorized” (actually: unauthenticated) response.
 
     @see unauthenticated
   */
@@ -549,12 +652,18 @@ export interface KittenResponse extends PolkaResponse {
   error (body?:string):void
 
   /**
-    General shorthand helper for setting the status code and
-    ending the response with an optional body.
+    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/
+*/
 export interface KittenPostRequest extends KittenRequest {
   uploads: Upload[]
 }