@possumtech/sqlrite 0.1.2 → 0.1.5

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

@@ -47,7 +47,7 @@ them all.
 
 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.
+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,
@@ -55,7 +55,36 @@ This is where you should create your tables, for example.
 	 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.
+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**
 
@@ -83,6 +112,9 @@ END TRANSACTION;
 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;
 ```
@@ -101,32 +133,53 @@ 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();
-
 ```
 
 ## 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
+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/",
 });
 ```
+
+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

@@ -16,22 +16,43 @@ export default class SqlRite {
 		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;
 
+		const initChunks = [];
+		const execChunks = [];
+		const prepChunks = [];
+
 		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;
-			}
+
+			if (type === "INIT") initChunks.push(chunk.groups);
+			if (type === "EXEC") execChunks.push(chunk.groups);
+			if (type === "PREP") prepChunks.push(chunk.groups);
 		}
+
+		initChunks.forEach((init) => db.exec(init.sql));
+
+		execChunks.forEach((exec) => {
+			this[exec.name] = () => db.exec(exec.sql);
+			this.async[exec.name] = async () => db.exec(exec.sql);
+		});
+
+		prepChunks.forEach((prep) => {
+			this[prep.name] = db.prepare(prep.sql);
+
+			this.async[prep.name] = {};
+
+			this.async[prep.name].all = async (params = {}) =>
+				this[prep.name].all(params);
+
+			this.async[prep.name].get = async (params = {}) =>
+				this[prep.name].get(params);
+
+			this.async[prep.name].run = async (params = {}) =>
+				this[prep.name].run(params);
+		});
 	}
 }

package/biome.json

@@ -7,7 +7,7 @@
 	},
 	"files": {
 		"ignoreUnknown": false,
-		"ignore": []
+		"ignore": ["SqlRite.d.ts", "package.json", "package-lock.json"]
 	},
 	"formatter": {
 		"enabled": true,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@possumtech/sqlrite",
-	"version": "0.1.2",
+	"version": "0.1.5",
 	"description": "SQL Done Right",
 	"keywords": [
 		"node",

package/sql/test.sql

@@ -21,5 +21,8 @@ END TRANSACTION;
 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

@@ -12,6 +12,8 @@ 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();