Add missing docs (#16)

* up to db ext

* add db specific docs

Author: lucasavila00

TODO.md

@@ -1 +1,69 @@
-TODO
+---
+title: Clickhouse Usage
+nav_order: 23
+parent: Examples
+layout: default
+---
+
+<details open markdown="block">
+  <summary>
+    Table of contents
+  </summary>
+  {: .text-delta }
+1. TOC
+{:toc}
+</details>
+
+```ts eval --replacePrintedInput=../src,sql-select-ts
+const ClickHouse = require("@apla/clickhouse");
+import { table, AnyStringifyable, RowsArray } from "../src";
+```
+
+With a DB connector
+
+```ts eval
+const db = new ClickHouse({
+    host: "localhost",
+    port: 8124,
+    user: "default",
+    password: "",
+    dataObjects: true,
+});
+
+const runS = async (q: string): Promise<any[]> =>
+    db.querying(q).then((it: any) => it.data);
+```
+
+We can implement a version that is aware of the types
+
+```ts eval
+const run = <T extends AnyStringifyable>(it: T): Promise<RowsArray<T>> =>
+    runS(it.stringify());
+```
+
+Then, with some tables
+
+```ts eval
+const t1 = table(["x", "y"], "t1");
+await runS(`DROP TABLE IF EXISTS t1`);
+await runS(`CREATE TABLE IF NOT EXISTS t1(x Int64, y Int64) ENGINE = Memory`);
+await runS(`INSERT INTO t1 VALUES(1,2)`);
+```
+
+We can run queries
+
+```ts eval --yield=json
+const value = await run(t1.selectStar());
+yield value;
+```
+
+Typescript knows the identifiers
+
+```ts eval --yield=json
+yield value.map((it) => it.x);
+```
+
+```ts eval
+//@ts-expect-error
+value.map((it) => it.u);
+```

docs-eval/clickhouse-usage.md

@@ -14,12 +14,12 @@ layout: default
 {:toc}
 </details>
 
-# From Nothing
-
 ```ts eval --replacePrintedInput=../src,sql-select-ts
 import { fromNothing, sql, table, unionAll } from "../src";
 ```
 
+# From Nothing
+
 ## Select
 
 ```ts eval --yield=sql
@@ -42,6 +42,18 @@ yield fromNothing({
     .stringify();
 ```
 
+## Select from Select
+
+```ts eval --yield=sql
+yield fromNothing({
+    it: sql(0),
+})
+    .selectStar()
+    .select((f) => ({ it2: f.it }))
+    .selectStar()
+    .stringify();
+```
+
 # From Tables
 
 We will use these tables

docs-eval/select.md

@@ -1 +1,65 @@
-TODO
+---
+title: SQLite Usage
+nav_order: 23
+parent: Examples
+layout: default
+---
+
+<details open markdown="block">
+  <summary>
+    Table of contents
+  </summary>
+  {: .text-delta }
+1. TOC
+{:toc}
+</details>
+
+```ts eval --replacePrintedInput=../src,sql-select-ts
+import sqlite from "sqlite3";
+import { table, AnyStringifyable, RowsArray } from "../src";
+```
+
+With a DB connector
+
+```ts eval
+const it = sqlite.verbose();
+const db = new it.Database(":memory:");
+
+const runS = (q: string) =>
+    new Promise<any[]>((rs, rj) =>
+        db.all(q, (e: any, r: any) => (e ? rj(e) : rs(r)))
+    );
+```
+
+We can implement a version that is aware of the types
+
+```ts eval
+const run = <T extends AnyStringifyable>(it: T): Promise<RowsArray<T>> =>
+    runS(it.stringify());
+```
+
+Then, with some tables
+
+```ts eval
+const t1 = table(["a", "b", "c"], "t1");
+await runS(`CREATE TABLE t1(a,b,c);`);
+await runS(`INSERT INTO t1 VALUES(1,2,3);`);
+```
+
+We can run queries
+
+```ts eval --yield=json
+const value = await run(t1.selectStar());
+yield value;
+```
+
+Typescript knows the identifiers
+
+```ts eval --yield=json
+yield value.map((it) => it.a);
+```
+
+```ts eval
+//@ts-expect-error
+value.map((it) => it.u);
+```

docs-eval/sqlite-usage.md

@@ -14,4 +14,73 @@ layout: default
 {:toc}
 </details>
 
-TODO
+```ts eval --replacePrintedInput=../src,sql-select-ts
+import * as io from "io-ts";
+import { AnyStringifyable, SelectionOf, table, RowOf, RowsArray } from "../src";
+```
+
+```ts eval
+const t = table(["a", "b"], "t");
+const q = t.selectStar();
+```
+
+# Getting Response Keys
+
+```ts eval
+type K = SelectionOf<typeof q>; // typeof K = 'a' | 'b'
+
+// @ts-expect-error
+const k2: K = "c";
+```
+
+# Response Object
+
+```ts eval
+type R1 = RowOf<typeof q>; // typeof Ret = {a: string | number | null | undefined, b: string | number | null | undefined, }
+const ret1: R1 = { a: 1, b: null };
+//@ts-expect-error
+ret1.c;
+```
+
+# Response Array
+
+```ts eval
+type R2 = RowsArray<typeof q>; // typeof Ret = {a: string | number | null | undefined, b: string | number | null | undefined, }[]
+const ret2: R2 = [] as any;
+//@ts-expect-error
+ret2?.[0]?.abc;
+```
+
+# Usage with io-ts
+
+```ts eval
+const ioTsResponse = <
+    T extends AnyStringifyable,
+    C extends { [key in SelectionOf<T>]: io.Mixed }
+>(
+    _it: T,
+    _codec: C
+): Promise<io.TypeOf<io.TypeC<C>>[]> => {
+    // Get the query string with it.stringify()
+    // and implement the DB comms.
+    return Promise.resolve([]);
+};
+```
+
+```ts eval
+const response = await ioTsResponse(t.selectStar(), {
+    a: io.string,
+    b: io.number,
+});
+
+response[0]?.a.charAt(0);
+response[0]?.b.toPrecision(2);
+
+//@ts-expect-error
+response[0]?.c;
+```
+
+```ts eval
+// @ts-expect-error
+ioTsResponse(t.selectStar(), { a: io.string });
+```

docs-eval/typed-response.md

@@ -0,0 +1,65 @@
+---
+title: Union (Compound)
+nav_order: 25
+parent: Examples
+layout: default
+---
+
+<details open markdown="block">
+  <summary>
+    Table of contents
+  </summary>
+  {: .text-delta }
+1. TOC
+{:toc}
+</details>
+
+```ts eval --replacePrintedInput=../src,sql-select-ts
+import { table, union, unionAll, except, intersect } from "../src";
+```
+
+We will use these tables
+
+```sql
+CREATE TABLE users(id int, age int, name string);
+CREATE TABLE admins(id int, age int, name string);
+```
+
+Which are defined in typescript as
+
+```ts eval
+const users = table(
+    /* columns: */ ["id", "age", "name"],
+    /* db-name & alias: */ "users"
+);
+
+const admins = table(
+    /* columns: */ ["id", "age", "name"],
+    /* alias: */ "adm",
+    /* db-name: */ "admins"
+);
+```
+
+# Union
+
+```ts eval --yield=sql
+yield union([admins.selectStar(), users.selectStar()]).stringify();
+```
+
+# Union All
+
+```ts eval --yield=sql
+yield unionAll([admins.selectStar(), users.selectStar()]).stringify();
+```
+
+# Except
+
+```ts eval --yield=sql
+yield except([admins.selectStar(), users.selectStar()]).stringify();
+```
+
+# Intersect
+
+```ts eval --yield=sql
+yield intersect([admins.selectStar(), users.selectStar()]).stringify();
+```