From f26089add6c6fc4eb9f86d220a2382591b843956 Mon Sep 17 00:00:00 2001 From: CRBroughton Date: Thu, 11 Apr 2024 08:11:26 +0100 Subject: [PATCH] docs: :memo: sync readmes across implementations, add libsql information --- README.md | 15 ++++++++++++-- src/bun/README.md | 47 +++++++++++++++++++++++++++++++++++++++++--- src/libsql/README.md | 47 +++++++++++++++++++++++++++++++++++++++++--- 3 files changed, 101 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 3a68fba..48baef0 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Sibyl -Sibyl is a lightweight SQLite query builder for SQL.js and Bun's sqlite3 driver, providing a Prisma-like query builder. Sibyl is in early development, +Sibyl is a lightweight SQLite query builder for libSQL, Bun's sqlite3 driver, and libSQL, providing a Prisma-like query builder. Sibyl is in early development, so expect breaking changes and rapid development. ## Getting Started @@ -29,11 +29,22 @@ Bun documentation. The Bun implemenation of Sibyl can be installed with the following command: ```bash -bun install @crbroughton/sibyl:bun +bun install @crbroughton/sibyl_bun ``` Sibyl will then accept the native Bun SQLite `Database`, again, see the Bun documentation. +#### libSQL Installation + +The libSQL implemenation of Sibyl can be installed +with the following command: + +```bash +bun install @crbroughton/sibyl_libsql libsql +``` +Sibyl will then accept libSQL `Database`, then see the +libSQL Getting Started Guide. + #### Getting Started To start off with Sibyl, you'll first have to ensure Sibyl is able to be run inside diff --git a/src/bun/README.md b/src/bun/README.md index e14e23d..48baef0 100644 --- a/src/bun/README.md +++ b/src/bun/README.md @@ -1,6 +1,6 @@ # Sibyl -Sibyl is a lightweight SQLite query builder for SQL.js and Bun's sqlite3 driver, providing a Prisma-like query builder. Sibyl is in early development, +Sibyl is a lightweight SQLite query builder for libSQL, Bun's sqlite3 driver, and libSQL, providing a Prisma-like query builder. Sibyl is in early development, so expect breaking changes and rapid development. ## Getting Started @@ -34,6 +34,17 @@ bun install @crbroughton/sibyl_bun Sibyl will then accept the native Bun SQLite `Database`, again, see the Bun documentation. +#### libSQL Installation + +The libSQL implemenation of Sibyl can be installed +with the following command: + +```bash +bun install @crbroughton/sibyl_libsql libsql +``` +Sibyl will then accept libSQL `Database`, then see the +libSQL Getting Started Guide. + #### Getting Started To start off with Sibyl, you'll first have to ensure Sibyl is able to be run inside @@ -89,12 +100,13 @@ createTable('firstTable', { // inferred table name and entry id: { autoincrement: true, type: 'INTEGER', // only allows for known data types ('int', 'char', 'blob') - nullable: false, primary: true, unique: true, }, job: { - type: 'char', + type: 'varchar', + size: 100, // specify the size of the varchar + nullable: true }, name: { type: 'char', @@ -222,6 +234,14 @@ const updatedEntry = Update('firstTable', { // infers the table and response typ } }) ``` +### Primary type + +Sibyl offers a custom type, called the 'primary' type. When using +this type, Sibyl will automatically set the entry to a primary key, +not nullable and unique. Sibyl will also ensure that the underlying +type changes, so your editor gives feedback about no longer requiring +you to manually set these keys. Currently the primary type is only +available as an integer type. ### Sibyl Responses @@ -230,6 +250,27 @@ when wanting to convert data types to TypeScript types; At the moment the custom only support boolean conversions from `boolean` to `0 | 1`. It's recommended to use this type as a wrapper, if you're ever using boolean values. +### Working With Reactivity + +When working with any front-end framework, you'll want to combine +Sibyl with your frameworks reactivity engine. I've provided some +examples in the playground, in this case using Vue, but in general +you should follow the following rules: + +- Sibyl is not responsive by default; You should aim for Sibyls +responses to end up in a reactive object (see ref for Vue). +- When working with your reactive state, it's good practice to ensure +that the states type is the same of that of the response type from +Sibyl +- Sibyl provides the `SibylResponse` type; You can use this type +as a 'wrapper' type like so: + +```typescript +const results = ref[]>([]) +``` +This ensures that when you work with the `results` array, it conforms +to the shape and type Sibyl will return. + ## Development To install dependencies: diff --git a/src/libsql/README.md b/src/libsql/README.md index e14e23d..48baef0 100644 --- a/src/libsql/README.md +++ b/src/libsql/README.md @@ -1,6 +1,6 @@ # Sibyl -Sibyl is a lightweight SQLite query builder for SQL.js and Bun's sqlite3 driver, providing a Prisma-like query builder. Sibyl is in early development, +Sibyl is a lightweight SQLite query builder for libSQL, Bun's sqlite3 driver, and libSQL, providing a Prisma-like query builder. Sibyl is in early development, so expect breaking changes and rapid development. ## Getting Started @@ -34,6 +34,17 @@ bun install @crbroughton/sibyl_bun Sibyl will then accept the native Bun SQLite `Database`, again, see the Bun documentation. +#### libSQL Installation + +The libSQL implemenation of Sibyl can be installed +with the following command: + +```bash +bun install @crbroughton/sibyl_libsql libsql +``` +Sibyl will then accept libSQL `Database`, then see the +libSQL Getting Started Guide. + #### Getting Started To start off with Sibyl, you'll first have to ensure Sibyl is able to be run inside @@ -89,12 +100,13 @@ createTable('firstTable', { // inferred table name and entry id: { autoincrement: true, type: 'INTEGER', // only allows for known data types ('int', 'char', 'blob') - nullable: false, primary: true, unique: true, }, job: { - type: 'char', + type: 'varchar', + size: 100, // specify the size of the varchar + nullable: true }, name: { type: 'char', @@ -222,6 +234,14 @@ const updatedEntry = Update('firstTable', { // infers the table and response typ } }) ``` +### Primary type + +Sibyl offers a custom type, called the 'primary' type. When using +this type, Sibyl will automatically set the entry to a primary key, +not nullable and unique. Sibyl will also ensure that the underlying +type changes, so your editor gives feedback about no longer requiring +you to manually set these keys. Currently the primary type is only +available as an integer type. ### Sibyl Responses @@ -230,6 +250,27 @@ when wanting to convert data types to TypeScript types; At the moment the custom only support boolean conversions from `boolean` to `0 | 1`. It's recommended to use this type as a wrapper, if you're ever using boolean values. +### Working With Reactivity + +When working with any front-end framework, you'll want to combine +Sibyl with your frameworks reactivity engine. I've provided some +examples in the playground, in this case using Vue, but in general +you should follow the following rules: + +- Sibyl is not responsive by default; You should aim for Sibyls +responses to end up in a reactive object (see ref for Vue). +- When working with your reactive state, it's good practice to ensure +that the states type is the same of that of the response type from +Sibyl +- Sibyl provides the `SibylResponse` type; You can use this type +as a 'wrapper' type like so: + +```typescript +const results = ref[]>([]) +``` +This ensures that when you work with the `results` array, it conforms +to the shape and type Sibyl will return. + ## Development To install dependencies: