@possumtech/sqlrite 0.1.1 → 0.1.2

package/README.md

@@ -5,41 +5,64 @@ 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 database is first created.
+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.
 
 **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,42 +70,49 @@ 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: 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();
+console.log(`The highest paid employee is ${employee.name}.`);
 
-	console.log(employee.name);
-})();
-```
+sql.deleteTable();
 
+```
 
 ## Installation
 
 Navigate to your project directory and run the following command:
 
 ```bash
-npm install sqlrite
+npm install @possumtech/sqlrite
 ```
 
 ## Configuration
@@ -98,7 +128,5 @@ const sql = new sqlrite(options = {
 		dir: "./sql",
 });
 ```
-
-Additional arguments to the
-[native sqlite module](https://nodejs.org/api/sqlite.html) can be passed as
-well.
+Additional arguments will be passed to the options object of the native sqlite
+module.

package/SqlRite.js

@@ -0,0 +1,37 @@
+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("");
+
+		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);
+					break;
+				case "PREP":
+					this[name] = db.prepare(sql);
+					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": []
+	},
+	"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.2",
 	"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,25 @@
+-- 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: getHighestPaidEmployee
+SELECT name FROM employees ORDER BY salary DESC LIMIT 1;

package/test/test.js

@@ -0,0 +1,17 @@
+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");
+
+console.log(`The highest paid employee is ${employee.name}.`);
+
+sql.deleteTable();