@possumtech/sqlrite 0.1.1 → 0.1.4

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# sqlrite Contributor Code of Conduct
+
+sqlrite is an open source project and not a community. It exists to perform the
+technical goals outlined in the readme and implemented in the codebase. All
+contributions are equally welcome, except from those who reject the premise that
+Sqlrite is an open source project and not a community.
+
+Those seeking a "community" are encouraged to reach out to a local church,
+mosque, temple, synagogue, or local civic organization, at your discretion, for
+community support. sqlrite does not support or endorse any cause or campaign.
+
+Conversations on the platform are to pertain to the project. All other topics
+are unwelcome.

package/CONTRIBUTING.md

@@ -0,0 +1 @@
+Contributions are welcome, and I will do my best to work with you on any workflow, coding style, or other issues that may arise.

package/README.md

@@ -5,41 +5,93 @@ SQL Done Right
 ## About sqlrite
 
 The sqlrite package is a modern node module that delivers an opinionated
-alternative to ORMs.
+alternative to ORMs. It is a thin wrapper around the
+[native sqlite module](https://nodejs.org/api/sqlite.html), which
+enables one to separate SQL code from Javascript code.
 
 ## Opinions
 
-1. **SQL First**: SQL is the best way to interact with data.
+1. **SQL Supremacy**: Your application is data, and SQL is the best interface.
 
 2. **Standards**: Node is the standard for server-side web apps, and it now
 contains a native sqlite module. Sqlite is the standard for SQL.
 
 3. **Simplicity**: It takes as much time to master an ORM as it would take to
 just master SQL, and with worse performance. For all but the most distributed,
-concurrent, and custom use cases, sqlite is the best choice.
+concurrent, and custom use cases, sqlite is the simple, correct choice.
 
-4. **Security**: Inline SQL is insecure, hard to maintain, and error-prone.
+4. **Security**: Inline SQL is insecure, unmaintainable, and error-prone.
 
-5. **Separation**: SQL code should be in separate SQL files rather than
+5. **Speed**: By enforcing the use of prepared statements, sqlrite ensures that
+your queries are compiled and cached by the sqlite engine.
+
+6. **Separation**: SQL code should be in separate SQL files rather than
 scattered throughout your JS codebase.
 
-## Solution
+7. **Size**: By relying on the native sqlite module, and nothing else, sqlrite
+won't bloat your project with unnecessary dependencies. This thing is *tiny*.
+
+## Usage
 
 **SQL**
 
-Add a `sql` directory to your project and include as many `.sql` files as you
+Add a `sql` folder to your project and include as many `.sql` files as you
 wish, with whatever folder structure you like. Sqlrite will automatically load
 them all.
 
-Sqlrite automatically loads only two types of code, "transactions," and 
-"prepared statements." Transactions can contain multiple statements, and are
-best for operations like creating tables, views, and indexes. Prepared
-Statements are best for the queries you will be running.
+| Syntax              | Name                   | Description            |
+|---------------------|------------------------|------------------------|
+| `-- INIT: txName`   | Executed Transaction   | Executed transaction   |
+| `-- EXEC: txName`   | Executable Transaction | Executable transaction |
+| `-- PREP: stmtName` | Prepared Statements    | Prepared statement     |
+
+There are three types of "chunk" one can add to a `.sql` file:
+
+1. **INIT**: A transaction that is executed when the module is instantiated.
+This is where you should create your tables, for example.
+
+2. **EXEC**: A transaction that can be executed at any time. For example,
+	 dropping a table. This is where you should put your transactions that are
+	 not prepared statements, like maintaining your database.
+
+3. **PREP**: A prepared statement that can be executed at any time. This is
+where you should put your queries. After declaring a prepared statement, you can
+then run it with either the `.all({})`, `.get({})` or `.run({})` methods, as per
+the native sqlite API.
+
+| Method     | Description                                           |
+|------------|-------------------------------------------------------|
+| `.all({})` | Returns all rows that match the query.                |
+| `.get({})` | Returns the first row that matches the query.         |
+| `.run({})` | Executes the query and returns the (optional) result. |
+
+### Synchronous/Asynchronous
+
+The native sqlite module currently only supports synchronous operations. This
+can pose a performance issue in some common cases. Sqlrite addresses this by
+allowing one to run one's queries asynchronously by appending `.async`:
+
+For example, instead of:
+
+**Synchronous**
+
+```js
+console.log(sql.getPositions.all());
+```
+
+**Asynchronous**
+
+```js
+sql.async.getPositions.all().then((positions) => console.log(positions));
+```
+
 
 **Example SQL File**
 
 ```sql
--- TX: createEmployeeTable
+-- INIT: createEmployeeTable
+BEGIN TRANSACTION;
+
 CREATE TABLE IF NOT EXISTS employees (
 	id INTEGER PRIMARY KEY AUTOINCREMENT,
 	name TEXT NOT NULL,
@@ -47,58 +99,87 @@ CREATE TABLE IF NOT EXISTS employees (
 	salary REAL NOT NULL
 );
 
--- PS: addEmployee
+END TRANSACTION;
+
+-- EXEC: deleteTable
+BEGIN TRANSACTION;
+
+DROP TABLE IF EXISTS employees;
+
+END TRANSACTION;
+
+-- PREP: addEmployee
 INSERT INTO employees (name, position, salary)
 	VALUES ($name, $position, $salary);
 
--- PS: getTopEmployee
+-- PREP: getPositions
+SELECT name, position FROM employees;
+
+-- PREP: getHighestPaidEmployee
 SELECT name FROM employees ORDER BY salary DESC LIMIT 1;
 ```
 
 **Example Node File**
 
 ```js
-import sqlrite from "sqlrite";
+import SqlRite from "@possumtech/sqlrite";
 
-const sql = new sqlrite();
+const sql = new SqlRite();
 
-(async () => {
-	await sql.createEmployeeTable();
+sql.addEmployee.run({ name: "John", position: "CEO", salary: 99999 });
+sql.addEmployee.run({ name: "Jane", position: "COO", salary: 49998 });
+sql.addEmployee.run({ name: "Jack", position: "CFO", salary: 49997 });
+sql.addEmployee.run({ name: "Jill", position: "CIO", salary: 49996 });
 
-	await sql.addEmployee.run({ name: "John", position: "CEO", salary: 99999 });
-	await sql.addEmployee.run({ name: "Jane", position: "COO", salary: 49998 });
-	await sql.addEmployee.run({ name: "Jack", position: "CFO", salary: 49998 });
-	await sql.addEmployee.run({ name: "Jill", position: "CIO", salary: 49998 });
+const employee = sql.getHighestPaidEmployee.get();
 
-	const employee = await sql.getTopEmployee.get();
+assert(employee?.name === "John", "The highest paid employee should be John");
 
-	console.log(employee.name);
-})();
-```
+sql.async.getPositions.all().then((positions) => console.log(positions));
+
+console.log(`The highest paid employee is ${employee.name}.`);
 
+sql.deleteTable();
+```
 
 ## Installation
 
-Navigate to your project directory and run the following command:
+1. Navigate to your project directory and run the following command:
+
+```bash
+npm install @possumtech/sqlrite
+```
+
+2. Then create a `sql` directory in your project directory. This is where you
+will put your SQL files.
 
 ```bash
-npm install sqlrite
+mkdir sql
+cd sql
+touch exampleFile.sql
 ```
 
 ## Configuration
 
 ```js
-import sqlrite from "sqlrite";
+import SqlRite from "@possumtech/sqlrite";
 
-const sql = new sqlrite(options = {
-		// Custom SQLite database file path.
-		path: ":memory:",
+const sql = new SqlRite({
+	// SQLite database file path.
+	path: ":memory:",
 
-		// Path to your SQL directory.
-		dir: "./sql",
+	// Path to your SQL directory.
+	dir: "sql/",
 });
 ```
 
-Additional arguments to the
-[native sqlite module](https://nodejs.org/api/sqlite.html) can be passed as
-well.
+You will almost certainly wish to replace the `path` with a path to your
+database file. Otherwise, the database will be created in memory and lost when
+the process ends.
+
+```js
+const sql = new SqlRite({ path: "path/to/your/database.sqlite3" });
+```
+
+Additional arguments will be passed to the options object of the native sqlite
+module.

package/SqlRite.d.ts

@@ -0,0 +1,22 @@
+import { Database, DatabaseSync, Statement } from 'node:sqlite';
+
+interface SqlRiteOptions {
+	path?: string;
+	dir?: string;
+}
+
+interface SqlRiteAsyncPreparedStatements {
+	all: (params?: Record<string, any>) => Promise<any[]>;
+	get: (params?: Record<string, any>) => Promise<any>;
+	run: (params?: Record<string, any>) => Promise<void>;
+}
+
+interface SqlRiteAsyncMethods {
+	[key: string]: (() => Promise<void>) | SqlRiteAsyncPreparedStatements;
+}
+
+export default class SqlRite {
+	constructor(options?: SqlRiteOptions);
+	async: SqlRiteAsyncMethods;
+	[key: string]: (() => void) | Statement | SqlRiteAsyncMethods | any;
+}

package/SqlRite.js

@@ -0,0 +1,45 @@
+import fs from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+
+export default class SqlRite {
+	constructor(options = {}) {
+		const defaults = {
+			path: ":memory:",
+			dir: "sql/",
+		};
+
+		const merged = { ...defaults, ...options };
+
+		const db = new DatabaseSync(merged.path, merged);
+
+		const { dir } = merged;
+		const files = fs.readdirSync(dir);
+		const code = files.map((f) => fs.readFileSync(dir + f, "utf8")).join("");
+
+		this.async = {};
+
+		const chunks =
+			/-- (?<chunk>(?<type>INIT|EXEC|PREP): (?<name>\w+)\n(?<sql>.*?))($|(?=-- (INIT|EXEC|PREP):))/gs;
+
+		for (const chunk of code.matchAll(chunks)) {
+			const { type, name, sql } = chunk.groups;
+			switch (type) {
+				case "INIT":
+					db.exec(sql);
+					break;
+				case "EXEC":
+					this[name] = () => db.exec(sql);
+					this.async[name] = async () => db.exec(sql);
+					break;
+				case "PREP":
+					this[name] = db.prepare(sql);
+
+					this.async[name] = {};
+					this.async[name].all = async (params = {}) => this[name].all(params);
+					this.async[name].get = async (params = {}) => this[name].get(params);
+					this.async[name].run = async (params = {}) => this[name].run(params);
+					break;
+			}
+		}
+	}
+}

package/biome.json

@@ -0,0 +1,30 @@
+{
+	"$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+	"vcs": {
+		"enabled": false,
+		"clientKind": "git",
+		"useIgnoreFile": false
+	},
+	"files": {
+		"ignoreUnknown": false,
+		"ignore": ["SqlRite.d.ts", "package.json", "package-lock.json"]
+	},
+	"formatter": {
+		"enabled": true,
+		"indentStyle": "tab"
+	},
+	"organizeImports": {
+		"enabled": true
+	},
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": true
+		}
+	},
+	"javascript": {
+		"formatter": {
+			"quoteStyle": "double"
+		}
+	}
+}

package/package.json

@@ -1,8 +1,14 @@
 {
 	"name": "@possumtech/sqlrite",
-	"version": "0.1.1",
+	"version": "0.1.4",
 	"description": "SQL Done Right",
-	"keywords": ["node", "sqlite", "sql", "orm", "database"],
+	"keywords": [
+		"node",
+		"sqlite",
+		"sql",
+		"orm",
+		"database"
+	],
 	"homepage": "https://github.com/possumtech/sqlrite#readme",
 	"bugs": {
 		"url": "https://github.com/possumtech/sqlrite/issues"
@@ -14,8 +20,9 @@
 	"license": "MIT",
 	"author": "@wikitopian",
 	"type": "module",
-	"main": "sqlrite.js",
+	"main": "SqlRite.js",
 	"scripts": {
-		"test": "node ./test/test.js"
+		"syntax": "npx @biomejs/biome check",
+		"test": "node --test"
 	}
 }

package/sql/test.sql

@@ -0,0 +1,28 @@
+-- INIT: createEmployeeTable
+BEGIN TRANSACTION;
+
+CREATE TABLE IF NOT EXISTS employees (
+	id INTEGER PRIMARY KEY AUTOINCREMENT,
+	name TEXT NOT NULL,
+	position TEXT NOT NULL,
+	salary REAL NOT NULL
+);
+
+END TRANSACTION;
+
+-- EXEC: deleteTable
+BEGIN TRANSACTION;
+
+DROP TABLE IF EXISTS employees;
+
+END TRANSACTION;
+
+-- PREP: addEmployee
+INSERT INTO employees (name, position, salary)
+	VALUES ($name, $position, $salary);
+
+-- PREP: getPositions
+SELECT name, position FROM employees;
+
+-- PREP: getHighestPaidEmployee
+SELECT name FROM employees ORDER BY salary DESC LIMIT 1;

package/test/test.js

@@ -0,0 +1,19 @@
+import assert from "node:assert";
+import SqlRite from "../SqlRite.js";
+
+const sql = new SqlRite();
+
+sql.addEmployee.run({ name: "John", position: "CEO", salary: 99999 });
+sql.addEmployee.run({ name: "Jane", position: "COO", salary: 49998 });
+sql.addEmployee.run({ name: "Jack", position: "CFO", salary: 49997 });
+sql.addEmployee.run({ name: "Jill", position: "CIO", salary: 49996 });
+
+const employee = sql.getHighestPaidEmployee.get();
+
+assert(employee?.name === "John", "The highest paid employee should be John");
+
+sql.async.getPositions.all().then((positions) => console.log(positions));
+
+console.log(`The highest paid employee is ${employee.name}.`);
+
+sql.deleteTable();