Initial commit

README.md

@@ -0,0 +1,140 @@
+# Prequel
+
+Streamlined, type-safe SQLite without too much _cruft_.
+
+_(I figured I should add on to the massive pile of sql-related projects called "prequel")_
+
+## Usage
+
+Prequel is designed to handle some of the boilerplate for getting going with a SQLite db. It handles setting up tables and basic CRUD statements and otherwise wraps a SQLite DB to allow for using raw SQL alongside the pre-built queries.
+
+```typescript
+import { Prequel } from "@foundry/prequel";
+
+interface UserRow {
+  user_id: number;
+  name: string;
+}
+
+const db = new Prequel("db.sqlite");
+const users = db.table("Users", {
+  user_id: {
+    type: "INTEGER",
+    primary: true,
+  },
+  name: "TEXT",
+});
+
+users.insertPartial({
+  name: "Flynn",
+});
+
+users.findAll(); // [{user_id: 1, name: "Flynn"}]
+
+const findByName = db.prepare<UserRow>(`SELECT * FROM ${users} WHERE name = ?`);
+findByName.get("Flynn"); // {user_id: 1, name: "Flynn"}
+```
+
+## Defining columns
+
+When defining the shape of a table, you can specify either a string containing a valid SQLite data type (limited to the five main types), or an object with further options.
+
+```typescript
+{
+  type: "TEXT", // or "INTEGER", "REAL", "BLOB", "NULL"
+  nullable: true, // Default is non-nullable columns
+  primary: true, // Default is non-primary column
+  misc: "" // Specify misc sql to append to the column def
+  references: othertable.reference() // Specifies a foreign key ref
+  cascade: true, // Cascading deletes. Default is off
+  default: "" // Optionally provide a default value
+}
+```
+
+## API
+
+### `new Prequel(filename?: string)`
+
+Creates a new `Prequel` object which wraps a SQLite db.
+
+### `prequel.table<RowShape>(name: string, columns: ColumnDefs)`
+
+Ensures the existance of the specified table in the DB
+
+### `prequel.prepare<RowShape, Params>(query: string)`
+
+Alias for the underlying `database.query` call, preparing a SQL statement and caching the statement if possible.
+
+### `prequel.enableWAL()`
+
+Executes the pragma statement to enable [WAL](https://www.sqlite.org/wal.html) mode
+
+### `prequel.close()`
+
+Safely close the database
+
+### `prequel.transaction(fn: () => void)`
+
+Execute a function within a transaction. If the function throws an error, the transaction is rolled back.
+
+Returns `true` when the transaction was successful. Throws any errors that occur during the transaction.
+
+### `new Table<RowShape>(db: Database | Prequel, name: string, columns: ColumnDefs)`
+
+Create a new table. Can be used without a Prequel object. If you pass in a Prequel object instead of a raw Database object, the table will be attached to the Prequel object as if it were created with `prequel.table()`
+
+### `table.reference(colName?: string)`
+
+Returns a reference usable with the `reference:` field in a column definition. Optionally provide a column name to reference. If no column name is provided, the tables primary key column is used.
+
+### `table.insert(data: RowShape)`
+
+Insert a fully formed row into the table
+
+### `table.insertPartial(data: Partial<RowShape>)`
+
+Insert a partial row into the table. Useful for generating IDs and leverage defaults.
+
+### `table.update(data: RowShape)`
+
+Given a complete row with a valid primary key value, update the row in the db.
+
+This can only be used if a column has been set to `primary: true`.
+
+### `table.findOnebyId(id: string | number)`
+
+Return a single row with the given ID
+
+### `table.findAll()`
+
+Return all of the rows in this table
+
+### `table.deleteById(id: string | number)`
+
+Delete a row with the given ID
+
+### `table.size()`
+
+Count the rows in the table
+
+### `table.toString()`
+
+The `toString()` behavior of a `Table` object returns the name of the table. This allows you to use the table object in queries for consistency:
+
+`SELECT * FROM ${users} WHERE user_id = ?`
+
+### `table.name`
+
+The name of the table
+
+### `table.db`
+
+The Database object this Table is a part of
+
+### `table.columns`
+
+A list of the column names on this table in the order they exist in the DB
+
+### `table.schema`
+
+The raw SQL that was used to generate this table