@small-web/kitten-types 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2023-04-14
+
+__Initial release__
+
+The successor to this module is Kitten Globals ([@small-web/kitten](https://codeberg.org/kitten/globals)), which has now been deprecated.
+
+For previous history, please see that module.

package/README.md

@@ -0,0 +1,136 @@
+# Kitten types
+
+Type-safety for [Kitten](https://kitten.small-web.org) apps and sites.
+
+This is a **types-only** package. It declares the global `kitten` namespace (via `declare global`) and exports reusable Kitten types you can use to annotate your own code.
+
+> 💡 The older [`@small-web/kitten`](https://www.npmjs.com/package/@small-web/kitten) module [has now been deprecated](#relationship-to-small-web-kitten). You should use this module for new projects and plan on migrating existing projects over to it going forward.
+
+## Install
+
+```shell
+npm install --save-dev @small-web/kitten-types
+```
+
+## Use
+
+Kitten exposes a global `kitten` namespace at runtime.
+
+This makes it easy to get up and running when learning, prototyping, or just building something quick without having to worry about type safety (you don’t have to import any packages to get started with building Kitten apps).
+
+Here’s a quick Hello World example that greets you with a smiley face:
+
+```js
+export default () => kitten.html`
+  <h1>Hello, world! <${kitten.icons.Smiley} /></h1>
+`
+```
+
+> 💡 Put the above code in a file called _index.page.js_ and run `kitten` from the same directory if you want to follow along.
+
+While it works, you won’t get language intelligence for the `kitten` global, so you won’t be able to, for example, see all the other possible `kitten.icons` you could be using.
+
+How you add language intelligence and static type checking for Kitten to your project differs based on whether you’re using JavaScript or [TypeScript](https://www.typescriptlang.org/).
+
+### JavaScript
+
+1. [Install Kitten Types (@small-web/kitten-types)](#install) as a development-time dependency.
+2. *Either* add `@ts-check` to the tops of your JavaScript files or add a jsconfig.json file to your project to enable type checking.
+
+That’s it!
+
+In a JavaScript project, the global types will automatically be picked up by the TypeScript language server.
+
+So your example becomes the following with full type safety and intelligence:
+
+```js
+// @ts-check
+export default () => kitten.html`
+  <h1>Hello, world! <${kitten.icons.Smiley} /></h1>
+`
+```
+
+To add type annotations to your project, you can use [JSDoc](https://jsdoc.app/).
+
+### TypeScript
+
+There’s one extra step (compared to JavaScript) when using TypeScript.
+
+1. [Install Kitten Types (@small-web/kitten-types)](#install) as a development-time dependency.
+
+2. Create a tsconfig.json file.
+
+3. Create a *globals.d.ts* file in your project:
+
+   ```ts
+   import '@small-web/kitten-types'
+   export {}
+   ```
+
+
+That’s it!
+
+The global `kitten` type information will now be picked up by your editor.
+
+### Importing types for explicit annotations
+
+When you need to annotate function parameters, etc., import the types directly.
+
+In TypeScript:
+
+```ts
+import type { KittenRequest, KittenResponse } from '@small-web/kitten-types'
+
+export default ({ request, response }: { request: KittenRequest, response: KittenResponse }) =>
+  kitten.html`<h1>Kitten</h1>`
+```
+
+And, in JavaScript:
+
+```js
+// @ts-check
+/**
+  @param {{
+    request: import('@small-web/kitten-types').KittenRequest,
+    response: import('@small-web/kitten-types').KittenResponse
+  }} parameters
+*/
+export default ({ request, response }) => kitten.html`
+  <h1>Kitten</h1>
+`
+```
+
+> 🔗 For more help in using this module, please see the [Kitten Type Safety Tutorial](https://kitten.small-web.org/tutorials/type-safety/).
+
+## Database type safety
+
+Kitten by default has at least two [databases](https://kitten.small-web.org/reference/#database) per project:
+
+An internal database called `_db` and a custom one for you to use in your project called `db`.
+
+This package provides a type-safe `_db` export for the internal database as the structure is well known.
+
+If you want type safety for your custom project database, please create and use a type-safe database app module.
+
+> 🔗 For a more in-depth look into database type safety, please see the [Database App Modules Kitten Tutorial](https://kitten.small-web.org/tutorials/database-app-modules/).
+
+## Relationship to `@small-web/kitten`
+
+The older [`@small-web/kitten`](https://www.npmjs.com/package/@small-web/kitten) globals module cast the members of  `globalThis.kitten` at runtime and provided type safety for JavaScript projects (prior to TypeScript support being added to Kitten). 
+
+This was problematic as a discrepency between Kitten and the globals module was not just a missing completion in your editor but could break your app at runtime.  
+
+The `@small-web/kitten` package is now deprecated but kept available for backwards compatibility. It also now sources all of its types from this package (`@small-web/kitten-types`).
+
+New projects should use this types-only package and existing projects should be migrated over.
+
+## Like this? Fund us!
+
+[Small Technology Foundation](https://small-tech.org) is a tiny, independent not-for-profit.
+
+We exist in part thanks to patronage by people like you. If you share [our vision](https://small-tech.org/about/#small-technology) and want to support our work, please [become a patron or donate to us](https://small-tech.org/fund-us) today and help us continue to exist.
+
+## License
+
+Copyright © 2026-present [Aral Balkan](https://ar.al), [Small Technology Foundation](https://small-tech.org)
+Released under [AGPL 3.0](https://www.gnu.org/licenses/agpl-3.0.en.html).

package/global.d.ts

@@ -0,0 +1,288 @@
+// @small-web/kitten-types — ambient declaration of the global `kitten` namespace.
+//
+// This file declares the shape of `globalThis.kitten` so that consumers can use
+// the `kitten` global directly with full type safety, without importing a
+// runtime shim purely for types.
+//
+// The `KittenGlobal` interface is the single, hand-written source of truth for
+// the global namespace shape (previously reconstructed from runtime casts in
+// `@small-web/kitten`’s `globals.js`).
+
+import type { EventEmitter } from 'node:events'
+import type { Server } from 'node:https'
+
+import type {
+  Session,
+  Upload,
+  KittenComponent,
+  KittenPage,
+  MarkdownIt,
+  Polka,
+  WebSocket as KittenWebSocket,
+  slugify as Slugify,
+  yaml as Yaml,
+  Point,
+  Signature
+} from './types.d.ts'
+
+import type { KittenIcons } from 'kitten-icons/types.d.ts'
+
+/** Tagged template function (e.g. `kitten.html`, `kitten.css`). */
+export type TaggedTemplate = (
+  strings: TemplateStringsArray,
+  ...properties: any[]
+) => string | Array<string> | Promise<string | Array<string>>
+
+/** Sanitisation helper (e.g. `kitten.safelyAddHtml`, `kitten.sanitise`). */
+export type SanitisationFunction = (
+  untrustedContent: string,
+  allowedTags?: Array<string>,
+  contact?: boolean
+) => string
+
+type StatsObject = Record<string, number>
+
+/** Internal Kitten database (`kitten._db`). */
+export interface KittenInternalDb {
+  sessions: Record<string, Session>
+  settings: {
+    autoUpdate: {
+      interval: number
+    }
+    domainToken: string
+    evergreenWebUrl: string
+    hideWelcomeMessage: boolean
+    id: {
+      ed25519: {
+        asString: string
+      }
+      ssh: {
+        asString: string
+        fingerprint: string
+      }
+    }
+    packageLockFileHashes: Record<string, string>
+    path: string
+    smallWebHostDomain: string
+    stats: {
+      hits: StatsObject
+      pages: StatsObject
+      missing: StatsObject
+      referrers: StatsObject
+      serverErrors: StatsObject
+    }
+    uploads: UploadStore
+    webhookSecret: string
+  }
+  uploads: Record<string, Upload>
+}
+
+/** The `kitten.uploads` store. */
+export type UploadStore = {
+  get(id: string): Upload
+  length(): number
+  all(): Upload[]
+  allIds(): string[]
+  delete(id: string): Promise<void>
+} & Record<string, Upload>
+
+interface ServerOptions {
+  domain?: string
+  port?: number
+  aliases?: string
+  open?: boolean
+  'working-directory'?: string
+  'domain-token'?: string
+  'small-web-host-domain'?: string
+}
+
+/**
+  The shape of the global `kitten` namespace.
+*/
+export interface KittenGlobal {
+  version: {
+    date: Date
+    versionStamp: number
+    gitHash: string
+    apiVersion: number
+    nodeVersion: string
+    exactVersion: string
+    birthday: string
+    starSign: string
+    Component: () => Function
+    html: () => string
+    printToConsole: () => void
+  }
+
+  app: {
+    package?: any
+    router: Polka
+    server: Server
+  }
+
+  // db is the custom database. If you want type safety for it, create a
+  // database app module in your project and declare the types there.
+  // See: https://codeberg.org/kitten/app#database-app-module
+  db: any
+
+  _db: KittenInternalDb
+
+  Upload: typeof Upload
+  uploads: UploadStore
+  icons: KittenIcons
+
+  domain: string
+  port: number
+
+  databaseDirectory: string
+  projectIdentifier: string
+
+  appRepository: {
+    upgradeAppToLatestCompatibleVersion(): Promise<void>
+    upgradeAppToLatestAvailableCommit(): Promise<void>
+    updateAppToVersion(versionTag: string): Promise<void>
+    update(): Promise<void>
+    hasCompatibleAppVersion: boolean
+    canBeUpdated: boolean
+    hasNewerApiVersion: boolean
+    upgradeOrDowngrade(versionTag: string, lowercase: boolean): 'upgrade' | 'downgrade'
+    isEqualToVersion(versionTag: string): boolean
+    UpdateButtonComponent(): (type: string, version: string, small: boolean) => string | Array<string>
+    VersionComponent(): (version: string, compatible: boolean, brief: boolean) => string | Array<string>
+    CurrentAppVersionComponent(): () => string | Array<string>
+    AllAvailableVersionsComponent(): () => string | Array<string>
+    displayAppVersion(): void
+  }
+
+  automaticUpdates: {
+    interval: number
+    intervalInHours: number
+    timeToNextCheck(): number
+    timeToNextCheckPretty(): string
+    start(): void
+    checkForUpdates(): Promise<void>
+    stop(): void
+  }
+
+  // Note the mapping: `package` is exposed here even though the runtime shim
+  // exports it as `_package` (because `package` is a reserved word in strict
+  // mode for value bindings). As an interface property name it is valid.
+  package: {
+    hasCompatibleVersion: boolean
+    isLatestReleaseVersion: boolean
+    isMoreRecentThanReleaseVersion: boolean
+    canBeUpgraded: boolean
+    upgrade(apiVersion: number | undefined): void
+    update(): Promise<void>
+  }
+
+  requests: Array<string>
+  pages: Record<string, KittenPage>
+  events: EventEmitter
+
+  Component: typeof KittenComponent
+  Page: typeof KittenPage
+
+  html: TaggedTemplate
+  css: TaggedTemplate
+  js: TaggedTemplate
+  markdown: TaggedTemplate
+  md: MarkdownIt
+
+  slugify: typeof Slugify
+  yaml: typeof Yaml
+
+  crypto: {
+    bytesToHex: (uint8a: Uint8Array) => string
+    decrypt: (sharedKey: Uint8Array, encoded: string | Uint8Array) => Uint8Array
+    emojiStringToSecret: (emojiString: string) => Uint8Array
+    encrypt: (sharedKey: Uint8Array, plaintext: string | Uint8Array) => Uint8Array
+    getSharedSecret: (
+      privateKey: Uint8Array | string | bigint | number,
+      publicKey: Uint8Array | string
+    ) => Promise<Uint8Array>
+    hexToBytes: (hex: string) => Uint8Array
+    randomBytes: (bytesLength?: number) => Uint8Array
+    random32ByteTokenInHex: () => string
+    secretToEmojiString: (secret: Uint8Array) => string
+    sign: (message: Uint8Array | string, privateKey: Uint8Array | string) => Promise<Uint8Array>
+    verify: (
+      sig: Uint8Array | string | Signature,
+      message: Uint8Array | string,
+      publicKey: Uint8Array | string | Point
+    ) => Promise<boolean>
+  }
+
+  utils: {
+    ALL_ROUTE_EXTENSIONS: Array<string>
+    BACKEND_EXTENSIONS: Array<string>
+    DEPENDENCY_EXTENSIONS: Array<string>
+    DYNAMIC_ROUTE_EXTENSIONS: Array<string>
+    FRONTEND_EXTENSIONS: Array<string>
+    HTTP_METHODS: Array<string>
+    STATIC_ROUTE_EXTENSIONS: Array<string>
+    classNameFromFilePath: (filePath: string, basePath: string) => string
+    classNameFromRoutePattern: (pattern: string) => string
+    db: {
+      keypathForChange(change: string): string
+    }
+    decodeFilePath: (filePath: string) => string
+    encodeFilePath: (filePath: string) => string
+    exitWithError: (message: string) => void
+    extensionCategories: {
+      backendRoutes: Array<string>
+      frontendRoutes: Array<string>
+      dependencies: Array<string>
+      dynamicRoutes: Array<string>
+      staticRoutes: Array<string>
+      allRoutes: Array<string>
+    }
+    extensionOfFilePath: (filePath: string) => string
+    getDomainsAndPort: (options: ServerOptions) => { domains: string[]; port: number }
+    getProjectIdentifierForDomain: (domain: string, port: number) => string
+    kittenAppPath: string
+    npm: (command: 'ci' | 'install', modulePath: string) => boolean
+    routePatternFromFilePath: (filePath: string, basePath: string) => string
+    runNpmCiOnModulePath: (modulePath: string) => void
+    setBasePath: (workingDirectory: string, pathToServe: string) => string
+    supportedExtensionsRegExp: RegExp
+  }
+
+  libraries: {
+    htmx: string
+    htmxIdiomorph: string
+    htmxWebSocket: string
+    alpineJs: string
+    water: string
+  }
+
+  page: {
+    html: 'HTML'
+    head: 'HEAD'
+    startOfBody: 'START_OF_BODY'
+    beforeLibraries: 'BEFORE_LIBRARIES'
+    afterLibraries: 'AFTER_LIBRARIES'
+    endOfBody: 'END_OF_BODY'
+  }
+
+  safelyAddHtml: SanitisationFunction
+  sanitise: SanitisationFunction
+
+  WebSocket: typeof KittenWebSocket
+
+  deprecationWarnings: Array<string>
+
+  paths: {
+    APP_DATA_DIRECTORY: string
+    APP_UPLOADS_DIRECTORY: string
+    APP_REPL_DIRECTORY: string
+  }
+
+  deploy: Function
+}
+
+declare global {
+  var kitten: KittenGlobal
+}
+
+export {}

package/index.d.ts

@@ -0,0 +1,43 @@
+// @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).
+
+// 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
+// (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 { 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'

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@small-web/kitten-types",
+  "version": "1.0.0",
+  "description": "Types-only package for Kitten: declares the global `kitten` namespace and exports Kitten types.",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts"
+    },
+    "./global.d.ts": "./global.d.ts",
+    "./types.d.ts": "./types.d.ts"
+  },
+  "type": "module",
+  "license": "AGPL-3.0",
+  "private": false,
+  "engines": {
+    "node": ">= 24",
+    "npm": ">= 8.0.0"
+  },
+  "homepage": "https://codeberg.org/kitten/types",
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/kitten/types"
+  },
+  "bugs": "https://codeberg.org/kitten/types/issues",
+  "funding": {
+    "type": "foundation",
+    "url": "https://small-tech.org/fund-us/"
+  },
+  "keywords": [
+    "Kitten",
+    "namespace",
+    "globals",
+    "type checking",
+    "static types",
+    "types",
+    "declare global",
+    "Small Web",
+    "Small Tech"
+  ],
+  "author": {
+    "name": "Aral Balkan",
+    "email": "aral@small-tech.org",
+    "url": "https://ar.al"
+  },
+  "peerDependencies": {
+    "@types/node": ">=24"
+  },
+  "dependencies": {
+    "@types/markdown-it": "^14.1.2",
+    "@types/node": ">=24",
+    "kitten-icons": "^4.1.0"
+  }
+}

package/polka/index.d.ts

@@ -0,0 +1,111 @@
+import type { IncomingMessage, ServerResponse } from 'http';
+import type { ListenOptions, Server } from 'net';
+
+// Parsed URL
+
+declare interface ParsedURL {
+	pathname: string;
+	search: string;
+	query: Record<string, string | string[]> | void;
+	raw: string;
+}
+
+declare function parse(req: IncomingMessage): ParsedURL;
+
+
+// Trouter 
+
+// Thank you: @fwilkerson, @stahlstift
+// ---
+
+/** @type {import('http').METHODS} */
+type Methods = 'ACL' | 'BIND' | 'CHECKOUT' | 'CONNECT' | 'COPY' | 'DELETE' | 'GET' | 'HEAD' | 'LINK' | 'LOCK' |'M-SEARCH' | 'MERGE' | 'MKACTIVITY' |'MKCALENDAR' | 'MKCOL' | 'MOVE' |'NOTIFY' | 'OPTIONS' | 'PATCH' | 'POST' | 'PRI' | 'PROPFIND' |  'PROPPATCH' |  'PURGE' | 'PUT' | 'REBIND' | 'REPORT' | 'SEARCH' | 'SOURCE' | 'SUBSCRIBE' | 'TRACE' | 'UNBIND' | 'UNLINK' | 'UNLOCK' | 'UNSUBSCRIBE';
+
+type Pattern = RegExp | string;
+
+declare class Trouter<T = Function> {
+	find(method: Methods, url: string): {
+		params: Record<string, string>;
+		handlers: T[];
+	};
+	add(method: Methods, pattern: Pattern, ...handlers: T[]): this;
+	use(pattern: Pattern, ...handlers: T[]): this;
+	all(pattern: Pattern, ...handlers: T[]): this;
+	get(pattern: Pattern, ...handlers: T[]): this;
+	head(pattern: Pattern, ...handlers: T[]): this;
+	patch(pattern: Pattern, ...handlers: T[]): this;
+	options(pattern: Pattern, ...handlers: T[]): this;
+	connect(pattern: Pattern, ...handlers: T[]): this;
+	delete(pattern: Pattern, ...handlers: T[]): this;
+	trace(pattern: Pattern, ...handlers: T[]): this;
+	post(pattern: Pattern, ...handlers: T[]): this;
+	put(pattern: Pattern, ...handlers: T[]): this;
+}
+
+// Polka
+
+type Promisable<T> = Promise<T> | T;
+type ListenCallback = () => Promisable<void>;
+
+declare namespace polka {
+	export interface IError extends Error {
+		code?: number;
+		status?: number;
+		details?: any;
+	}
+
+	export type NextHandler = (err?: string | IError) => Promisable<void>;
+	export type ErrorHandler<T extends Request = Request> = (err: string | IError, req: T, res: Response, next: NextHandler) => Promisable<void>;
+	export type Middleware<T extends IncomingMessage = Request> = (req: T & Request, res: Response, next: NextHandler) => Promisable<void>;
+
+	export interface IOptions<T extends Request = Request> {
+		server?: Server;
+		onNoMatch?: Middleware<T>;
+		onError?: ErrorHandler<T>;
+	}
+
+	export type Response = ServerResponse;
+
+	export interface Request 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;
+	}
+
+	export interface Polka<T extends Request = Request> extends Trouter<Middleware<T>> {
+		readonly server: Server;
+		readonly wares: Middleware<T>[];
+
+		readonly onError: ErrorHandler<T>;
+		readonly onNoMatch: Middleware<T>;
+
+		readonly handler: Middleware<T>;
+		parse: (req: IncomingMessage) => ParsedURL;
+
+		use(pattern: RegExp|string, ...handlers: (Polka<T> | Middleware<T>)[]): this;
+		use(...handlers: (Polka<T> | Middleware<T>)[]): this;
+
+		listen(port?: number, hostname?: string, backlog?: number, callback?: ListenCallback): this;
+		listen(port?: number, hostname?: string, callback?: ListenCallback): this;
+		listen(port?: number, backlog?: number, callback?: ListenCallback): this;
+		listen(port?: number, callback?: ListenCallback): this;
+		listen(path: string, backlog?: number, callback?: ListenCallback): this;
+		listen(path: string, callback?: ListenCallback): this;
+		listen(options: ListenOptions, callback?: ListenCallback): this;
+		listen(handle: any, backlog?: number, callback?: ListenCallback): this;
+		listen(handle: any, callback?: ListenCallback): this;
+	}
+}
+
+declare function polka<T extends polka.Request = polka.Request>(
+	options?: polka.IOptions<T>
+): polka.Polka<T>;
+
+export default polka;