sqlite3: Add type definitions, as a .js.flow rather than libdef

This is much, much nicer for actually writing the types than a
libdef would be.  In particular iterating on changes is much
faster and easier, because Flow does its usual incremental thing
rather than restarting from scratch on each edit.

More details in some new docs text in howto/libdefs.

Author: gnprice

.flowconfig

@@ -115,6 +115,9 @@ munge_underscores=true
 
 module.name_mapper='^react-native/\(.*\)$' -> '<PROJECT_ROOT>/node_modules/react-native/\1'
 module.name_mapper='^@?[./a-zA-Z0-9$_-]+\.\(bmp\|gif\|jpg\|jpeg\|png\|psd\|svg\|webp\|m4v\|mov\|mp4\|mpeg\|mpg\|webm\|aac\|aiff\|caf\|m4a\|mp3\|wav\|html\|pdf\)$' -> '<PROJECT_ROOT>/node_modules/react-native/Libraries/Image/RelativeImageStub'
+# This lets us write .js.flow files instead of libdefs.
+# Add more libraries as needed to this pattern with `\|`: `foo\|bar\|…`.
+module.name_mapper='^\(sqlite3\)$' -> '<PROJECT_ROOT>/types/\0'
 
 suppress_type=$FlowIssue
 suppress_type=$FlowFixMe

docs/howto/libdefs.md

@@ -17,6 +17,39 @@ dependencies well-typed.
 
 -----
 
+## Normal type definitions (`.js.flow`): `sqlite3`
+
+This library doesn't have its own Flow types, and doesn't have its own
+TypeScript types so it's not suited for Flowgen.  We wrote type
+definitions from scratch.
+
+For doing that, an option that's much more convenient than a libdef in
+`flow-typed` is to write a `.js.flow` file.  In particular iterating
+on changes is much faster and easier, because Flow does its usual
+incremental thing; whereas with a libdef it restarts from scratch on
+each edit.
+
+The major difference in structure between a libdef and a `.js.flow`
+file is that the latter doesn't have `declare module` blocks.
+Instead the whole file describes one module, identified by where it is
+in the filesystem -- just like a normal JS file does.  The contents of
+the file are very much like the body of any given `declare module`
+block in a libdef: `export type Foo = …` and `declare export class
+Bar { … }` and so on.
+
+In order to be able to write a `.js.flow` file for the library in our
+tree (rather than under `node_modules/`) and have Flow find it, we
+added the following line to `.flowconfig`:
+
+    module.name_mapper='^\(sqlite3\)$' -> '<PROJECT_ROOT>/types/\0'
+
+Then the file goes at `types/sqlite3.js.flow`.
+
+The actual contents of the `.js.flow` file were based on the library's
+API documentation, and consulting its implementation for points where
+the documentation wasn't clear.
+
+
 ## `remotedev-serialize`
 
 Some assembly was required for a libdef for `remotedev-serialize`, but

types/sqlite3.js.flow

@@ -0,0 +1,69 @@
+/*
+Types for the NPM package `sqlite3`.
+
+Based on upstream API docs:
+  https://github.com/mapbox/node-sqlite3/wiki/API
+
+@flow strict-local
+*/
+
+/* eslint-disable */
+
+// From `Statement::BindParameter` in the implementation.
+// It actually also accepts arbitrary objects using ToString,
+// but let's say that it doesn't.
+export type QueryParameter = string | number | boolean | null | RegExp | Date | Buffer;
+
+type Row = { ... };
+
+type ResultCallback<T> = interface { (Error): void, (null, T): void };
+
+declare export class Database {
+  constructor(filename: string): this; // not modeled: mode and callback
+
+  close(cb?: ResultCallback<void>): void;
+
+  // configure(…) not modeled
+
+  // Does the `run` callback get a second argument?  Not sure from docs.
+  // Not modeled here: the `this` on the `run` callback.
+  run(sql: string, params: QueryParameter[], cb?: ResultCallback<void>): this;
+  run(sql: string, cb?: ResultCallback<void>): this;
+
+  get(sql: string, params: QueryParameter[], cb?: ResultCallback<Row | void>): this;
+  get(sql: string, cb?: ResultCallback<Row | void>): this;
+
+  all(sql: string, params: QueryParameter[], cb?: ResultCallback<Row[]>): this;
+  all(sql: string, cb?: ResultCallback<Row[]>): this;
+
+  each(
+    sql: string,
+    params: QueryParameter[],
+    cb?: ResultCallback<Row>,
+    complete?: ResultCallback<number>,
+  ): this;
+  each(sql: string, cb?: ResultCallback<Row>, complete?: ResultCallback<number>): this;
+
+  exec(sql: string, cb?: ResultCallback<void>): this;
+
+  // Not modeled: the Statement class, and:
+  //   prepare(sql: string, params: QueryParameter[], cb?: ResultCallback<void>): Statement;
+  //   prepare(sql: string, cb?: ResultCallback<void>): Statement;
+
+  // The library also accepts forms one might write like:
+  //   all(sql: string, ...params: QueryParameter[], cb?: ResultCallback<Row[]>): this
+  // with the query parameters splatted right into the arguments list.
+  // But that means a variable-length list of arguments followed by another
+  // argument, which the Flow type system doesn't permit.  We include the
+  // zero-argument version of that for convenience; otherwise, pass an array.
+  //
+  // It also accepts `params` as an object like this:
+  //   db.run("UPDATE tbl SET name = $name WHERE id = $id", { $id: 2, $name: "bar" });
+  // We leave that out for now.
+}
+
+export default {
+  // `verbose` function not modeled
+  Database,
+  // Statement class not modeled
+};