TypeScript types

[schickling]

Would be nice if this library would provide TS types as well. I'm using the following WIP types in my app locally right now:

// TODO remove this once `@sqlite.org/sqlite-wasm` has types
declare module '@sqlite.org/sqlite-wasm' {
  export type TODO = any

  interface Window {
    // eslint-disable-next-line @typescript-eslint/consistent-type-imports
    sqlite3InitModule: (_?: TODO) => Promise<import('./sqlite3').Sqlite3>
  }

  export type Sqlite3 = {
    oo1: {
      DB: new (options?: OO1DBOptions) => DB
      OpfsDb: new (filename: string, mode: string) => DB
    }
    opfs?: {
      debug: TODO
      deleteEntry: TODO
      entryExists: TODO
      metrics: TODO
      mkdir: TODO
      randomFilename: TODO
      registerVfs: TODO
      rootDirectory: TODO
    }
    capi: {
      sqlite3_deserialize: TODO
      [key: string]: TODO
    }
    wasm: {
      allocFromTypedArray: (typedArray: Uint8Array) => number
      [key: string]: TODO
    }
  }

  /** https://sqlite.org/wasm/doc/trunk/api-oo1.md#db-ctor */
  export type OO1DBOptions = {
    /** @default ':memory:' */
    filename?: string
    /** open-mode flags */
    flags?: string
    /** name of the sqlite3_vfs to use */
    vfs?: string
  }

  export declare const InitWasm: () => Promise<Sqlite3>

  export default InitWasm

  export class DB {
    filename: string
    pointer: TODO

    affirmOpen(): DB

    changes(total: boolean, sixtyFour: boolean): number

    exec(options: ExecOptions): TODO
    exec(query: FlexibleString, options?: ExecOptions): TODO
    close(): DB
    export(): TODO
    /**
     * @example aDb.prepare("INSERT INTO foo(a) VALUES(?)").bind(123).stepFinalize();
     */
    prepare(query: FlexibleString): Stmt

    checkRc(db: TODO, resultCode: TODO)

    createFunction(): TODO

    dbFilename(): string

    dbName(): string
  }

  export type ExecOptions = {
    sql?: FlexibleString
    bind?: Bindable
    // saveSql?: TODO

    returnValue?: 'this' | 'resultRows' | 'saveSql'

    rowMode?: 'array' | 'object' | 'stmt'

    resultRows?: TODO[]
  }

  export type FlexibleString = string | Uint8Array | Int8Array | string[]

  /** https://sqlite.org/wasm/doc/trunk/api-oo1.md#stmt-properties */
  export interface Stmt {
    columnCount: number
    parameterCount: number
    pointer: TODO

    bind(bindable: Bindable): Stmt
    bind(indexOrParameterName: number | string, bindable: Bindable): Stmt

    stepFinalize(): boolean
  }

  export type Bindable = BindableValue[] | Record<string, BindableValue>

  export type BindableValue = null | undefined | number | boolean | string | Uint8Array | Int8Array
}

[tomayac]

This looks pretty complete. Do you want to open a quick PR and add this, Johannes?

[schickling]

This looks pretty complete.

It's actually not. 🙈 It has a ton of TODOs in there, so I hope someone else can take this as a foundation to create a more "complete" PR. 🙏

[sgbeal]

Please do not export the sqlite3.opfs namespace. That one is very specifically not intended for client-side use and is subject to change in any given build. Only namespaces described at:

https://sqlite.org/wasm/doc/trunk/api-index.md#namespace

should be exported.

[sgbeal]

PS: within the sqlite project, none of us use TypeScript (nor any node.js-related stuff beyond what emscripten requires for its behind-the-scenes work), so we make no effort to maintain this type of detail in the canonical tree. That's also the reason we don't use jsdoc doc syntax: we don't use any tools which can process them and don't want to add dependencies on tools we wouldn't otherwise use.

[sgbeal]

i need to leave for a couple of hours but will attempt to flesh out some of those here in the comments when i get back. e.g. DB.pointer is either undefined or an integer (WASM heap pointer).

[tomayac]

Let me take @schickling's types draft to a draft PR, and we can noodle on it there.

[tomayac]

Here we go: #2.

[tomayac]

Sorry, @schickling, just realized it's Johannes, not Jonas. Fixed in my comment above. I have invited you as a collaborator to the project.

[sgbeal]

Some notes/suggestions/caveats re. types:

• pointer type = undefined | integerZeroOrGreater
• The various DB constructors all accept (string name, string mode) as well as (OO1DBOptions options) formats.
• The sqlite3.capi namespace is huge and adding full typing info for it would be a significant undertaking. The list of functions and SQLITE_... constants exported there are listed in https://sqlite.org/wasm/doc/trunk/module-symbols.html, and the functions each link to their docs (many of which are the C API docs). That page also lists the public APIs of the sqlite3.wasm namespace, but does not link to their docs (https://sqlite.org/wasm/doc/trunk/api-wasm.md).
• The arguments for sqlite3InitModule() are not strictly public or stable. They are passed on directly to the Emscripten module-loading interface, so technically support anything that API does (noting that that API is subject to unpredictable change), but we don't encourage use of that argument because its handling is out of our control. The module-loading process does not give us a way to intercept or normalize those arguments, so clients cannot rely on any given module-loading options long-term.
• FlexibleString: may also be of type integerZeroOrGreater, in which case a WASM heap pointer to a UTF-8-encoded ([const] char *) is assumed. It may be of note that FlexibleStrings provided in Uint8Array and Int8Array form are required to be in UTF-8 encoding. Those given in string or string[] form will be recoded from JS to UTF-8 automatically.

That's all that comes to mind at the moment.

[sgbeal]

FYI: this related link just showed up in the sqlite forum and i've asked its poster (@mizchi) to join in over here:

https://gist.github.com/mizchi/cb572eae55154ec781ced5c111621939

[mandolyte]

I found that this in the root directory worked as a minimal declaration (it was suggested by vs-code):

declare module '@sqlite.org/sqlite-wasm';

[mizchi]

Here is my personal workaround of the type definition.

https://gist.github.com/mizchi/cb572eae55154ec781ced5c111621939

My version also expresses a pattern where the return value changes with the exec argument (returnValue and rowMode), but I don't think it's necessary to try hard to define strict return values on the API. Strictness as TypeScript should be guaranteed by an ORM that wraps sqlite-wasm, for example.

I think what the average user wants is an OO1 API, so as a first step, it would be nice to have the types there.

However, as you can see from official cookbook and other sources, the low-level sqlite3.capi.* also looks unavoidable. At the very least, it might be nice to know the capi property names.

I got that list from Object.keys(sqlite3.capi) on runtime.

[sgbeal]

I got that list from Object.keys(sqlite3.capi) on runtime.

Just FYI, there's a human-readable dump of that at: https://sqlite.org/wasm/doc/trunk/module-symbols.html

That one is generated from the version of the wasm/js running on that server, and that server is updated frequently (so is often more current than the latest release).

[jbaiter]

Here's another attempt at type hints based on @mizchi's work, but much expanded and with docstrings (based on the official documentation):
https://gist.github.com/jbaiter/d4a2a22c6c15571062f25d1dfea73218

The low-level APIs are as of yet untested and only based on the documentation, but I'll try to update them if I (or somebody else!) notice any mistakes.