GH Pages refinement

Author: ox-harris

docs2/README.md

@@ -0,0 +1,3 @@
+---
+redirect_to: ./index.md
+---

docs2/_config.yml

@@ -0,0 +1,8 @@
+title: LinkedQL
+description: SQL, evolved — A reactive, version-aware database client.
+plugins:
+  - jekyll-seo-tag
+  - jekyll-sitemap
+markdown: GFM
+url: "https://linked-db.github.io"
+baseurl: "/linked-ql"

docs2/entry/README.md

@@ -0,0 +1,3 @@
+---
+redirect_to: ./index.md
+---

docs2/entry/api.md

@@ -0,0 +1,68 @@
+---
+title: "The Query Interface"
+description: "The LinkedQL query interface"
+permalink: /entry/api/
+nav_order: 4
+layout: page
+---
+
+# Query Interface
+
+LinkedQL provides a **unified** query interface across all dialects.
+
+---
+
+## `2.1 |` `client.query()`
+
+Primary query API supporting multiple input shapes.
+
+```js
+// String query only
+const result = await client.query('SELECT * FROM users');
+
+// Query with parameters array
+const result = await client.query('SELECT * FROM users WHERE active = $1', [true]);
+
+// Query with parameters and options
+const result = await client.query(
+  'SELECT * FROM users WHERE created_at > $1',
+  [new Date('2024-01-01')],
+  { live: true }
+);
+
+// Parameters passed through options.values
+const result = await client.query(
+  'SELECT * FROM users WHERE name = $1',
+  { values: ['John'], cache: true }
+);
+```
+
+---
+
+## `2.2 |` `Result`
+
+Every query returns a `result` object exposing `.rows` and `.rowCount` (alias `.affectedRows`).
+
+```js
+// SELECT queries
+const result = await client.query('SELECT id, name, email FROM users');
+console.log(result.rows);     // [{ id: 1, name: 'John', email: '[email protected]' }]
+console.log(result.rowCount); // 0  (SELECT never affects rows)
+```
+
+```js
+// INSERT with RETURNING
+const result = await client.query(
+  'INSERT INTO users (name) VALUES ($1) RETURNING *',
+  ['Alice']
+);
+console.log(result.rows);     // [{ id: 2, name: 'Alice' }]
+console.log(result.rowCount); // 0  (.rowCount only applies to non-returning writes)
+```
+
+```js
+// INSERT without RETURNING
+const result = await client.query('INSERT INTO users (name) VALUES ($1)', ['Bob']);
+console.log(result.rowCount); // 1  (one row affected)
+console.log(result.rows);     // []  (no result set)
+```

docs2/entry/clients.md

@@ -0,0 +1,160 @@
+---
+title: "Clients and Dialects"
+description: "The LinkedQL clients and dialects"
+permalink: /entry/clients/
+nav_order: 4
+layout: page
+---
+
+# Dialects & Clients
+
+LinkedQL ships with clients for each major SQL dialect.
+
+Each LinkedQL client extends its respective native connector and accepts the same initialization options.
+The PostgreSQL, MySQL, and MariaDB clients integrate directly with their native drivers, while **FlashQL** provides an in-memory SQL engine that speaks both dialects.
+
+---
+
+## `1.1 |` PostgreSQL
+
+Use as a drop-in replacement for [`node-postgres`](https://www.npmjs.com/package/pg).<br>
+Speaks native **PostgreSQL**.
+
+```js
+import { PGClient } from '@linked-db/linked-ql/pg';
+
+const client = new PGClient({
+  host: 'localhost',
+  port: 5432,
+  user: 'postgres',
+  password: 'password',
+  database: 'mydb',
+  poolMode: false // defaults to pg.Client
+});
+await client.connect();
+
+const res = await client.query('SELECT 1::text AS result');
+console.log(res.rows); // [{ result: '1' }]
+
+await client.disconnect();
+```
+
+### `1.1.1 |` Client Options
+
+`PGClient` accepts all options supported by `node-postgres`.
+
+Additional options:
+
+* **`poolMode`** (*Default*: `false`) — whether to connect over `pg.Pool` or `pg.Client`.
+
+### `1.1.2 |` Realtime Setup
+
+To enable **live queries**, ensure [logical replication](https://www.postgresql.org/docs/current/view-pg-replication-slots.html) is enabled on your database.
+
+Optionally specify the following to adapt LinkedQL to your setup:
+
+* **`walSlotName`** — (*Default*: `'linkedql_default_slot'`) replication slot name.
+* **`walSlotPersistence`** — slot lifecycle management:<br>
+  `0` = ephemeral, DB-managed · `1` = ephemeral, LinkedQL-managed · `2` = persistent, external management implied.
+* **`pgPublications`** — (*Default*: `'linkedql_default_publication'`) publication name(s) to listen on.
+
+---
+
+## `1.2 |` MySQL
+
+Use in place of [`mysql2`](https://www.npmjs.com/package/mysql2).
+Speaks native **MySQL**.
+
+```js
+import { MySQLClient } from '@linked-db/linked-ql/mysql';
+
+const client = new MySQLClient({
+  host: 'localhost',
+  port: 3306,
+  user: 'root',
+  password: 'password',
+  database: 'mydb',
+  poolMode: false // defaults to mysql.createConnection()
+});
+await client.connect();
+
+const res = await client.query('SELECT 1 AS `result`');
+console.log(res.rows); // [{ result: 1 }]
+
+await client.disconnect();
+```
+
+### `1.2.1 |` Client Options
+
+`MySQLClient` accepts all connection options supported by `mysql2`.
+
+Additional options:
+
+* **`poolMode`** (*Default*: `false`) — whether to connect over `mysql.createPool()` or `mysql.createConnection()`.
+
+### `1.2.2 |` Realtime Setup
+
+Realtime capabilities for MySQL are **coming soon**.
+
+---
+
+## `1.3 |` MariaDB
+
+Use in place of [`mariadb`](https://www.npmjs.com/package/mariadb`).<br>
+Speaks native **MariaDB / MySQL**.
+
+```js
+import { MariaDBClient } from '@linked-db/linked-ql/mariadb';
+
+const client = new MariaDBClient({
+  host: 'localhost',
+  port: 3306,
+  user: 'root',
+  password: 'password',
+  database: 'mydb'
+});
+await client.connect();
+
+const res = await client.query('SELECT 1 AS `result`');
+console.log(res.rows); // [{ result: 1 }]
+
+await client.disconnect();
+```
+
+### `1.3.1 |` Client Options
+
+`MariaDBClient` accepts all connection options supported by the native `mariadb` driver.<br>
+It always runs on a connection pool.
+
+### `1.3.2 |` Realtime Setup
+
+Realtime support for MariaDB is **coming soon**.
+
+---
+
+## `1.4 |` FlashQL
+
+Use as an in-memory alternative to [`SQLite`](https://sqlite.org/) or [`PGLite`](https://pglite.dev/).
+Speaks both **PostgreSQL** and **MySQL** dialects.
+
+```js
+import { FlashClient } from '@linked-db/linked-ql/flash';
+
+const client = new FlashClient();
+await client.connect();
+
+// PostgreSQL syntax (default dialect)
+const pgRes = await client.query('SELECT 1::text AS result');
+console.log(pgRes.rows); // [{ result: '1' }]
+
+// MySQL syntax (explicit dialect)
+const myRes = await client.query('SELECT 1 AS `result`', { dialect: 'mysql' });
+console.log(myRes.rows); // [{ result: 1 }]
+
+await client.disconnect();
+```
+
+### `1.4.1 |` Realtime Setup
+
+Realtime capabilities are built in.
+No configuration required — FlashQL automatically emits and processes change events internally.

docs2/entry/index.md

@@ -0,0 +1,16 @@
+---
+title: "Entry Layer"
+description: "The interface layer that accepts SQL via .query(), routes it through the system, and connects to PostgreSQL, MySQL, MariaDB, and FlashQL."
+permalink: /entry/
+nav_order: 1
+layout: page
+---
+
+# Entry Layer (`entry`)
+
+The entry layer defines the interface between the user and the LinkedQL runtime.  
+It handles incoming SQL through `.query()`, orchestrates its passage through the Language and Processing layers,  
+and returns live results via dialect-specific clients.
+
++ [API (`api`)](api) — the query interface.
++ [Clients (`clients`)](clients) — clients and dialects.

docs2/flash/README.md

@@ -0,0 +1,3 @@
+---
+redirect_to: ./index.md
+---