documentation and bumping version number

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Jhagas Hana Winaya
+Copyright (c) 2023 Jhagas Hana Winaya, Achmad Nashruddin Riskynanda
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -10,67 +10,111 @@ For further information :
 - [Supabase Documentation](https://supabase.com/docs)
 - [PostgREST API Documentation](https://postgrest.org/en/stable/api.html)
 
+## Table of Contents
+
+- [ESP32 Supabase](#esp32-supabase)
+  - [Table of Contents](#table-of-contents)
+  - [Using This Library](#using-this-library)
+  - [Examples](#examples)
+  - [Available Method](#available-method)
+    - [Directly Makes Connection to Database](#directly-makes-connection-to-database)
+    - [Building The Queries](#building-the-queries)
+      - [Horizontal Filtering (comparison) Operator](#horizontal-filtering-comparison-operator)
+      - [Ordering, Limiting or Offseting the Result](#ordering-limiting-or-offseting-the-result)
+      - [Getting the Query URL (for debugging)](#getting-the-query-url-for-debugging)
+      - [Reset the Query URL](#reset-the-query-url)
+  - [To-do (sorted by priority)](#to-do-sorted-by-priority)
+
+## Using This Library
+
+This library is available at Arduino's Library Manager, as well as PlatformIO Library Manager
+- [Arduino Library Manager Guide](http://arduino.cc/en/guide/libraries)
+
 ## Examples
 
 See all examples in `examples` folder
 
 ## Available Method
 
-| Method                                                | Description                                                                 |
-| ----------------------------------------------------- | --------------------------------------------------------------------------- |
-| `begin(String url_a, String key_a);`                  | `url_a`  is a Supabase URL and `key_a` is supabase anon key. Returns `void` |
-| `login_email(String email_a, String password_a)`      | Returns http response code `int`                                            |
-| `login_phone(String phone_a, String password_a)`      | Returns http response code `int`                                            |
-| `insert(String table, String json, bool upsert)`      | Returns http response code `int`                                            |
-| `get_payload(String table, String json, bool upsert)` | Returns payload from select and rpc method `String`                         |
-
-### Horizontal Filtering Operators
-
-| Abbreviation | Meaning                                                                                                                                                                   |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| eq           | equals                                                                                                                                                                    |
-| gt           | greater than                                                                                                                                                              |
-| gte          | greater than or equal                                                                                                                                                     |
-| lt           | less than                                                                                                                                                                 |
-| lte          | less than or equal                                                                                                                                                        |
-| neq          | not equal                                                                                                                                                                 |
-| in           | one of a list of values, e.g. `?a=in.(1,2,3)` – also supports commas in quoted strings like `?a=in.("hi,there","yes,you")`                                                |
-| is           | checking for exact equality (null,true,false,unknown)                                                                                                                     |
-| cs           | contains e.g. `?tags=cs.{example, new}`                                                                                                                                   |
-| cd           | contained in e.g. `?values=cd.{1,2,3}`                                                                                                                                    |
-| ov           | overlap (have points in common), e.g. `?period=ov.[2017-01-01,2017-06-30]` – also supports array types, use curly braces instead of square brackets e.g.  `?arr=ov.{1,3}` |
-| sl           | strictly left of, e.g. `?range=sl.(1,10)`                                                                                                                                 |
-| sr           | strictly right of                                                                                                                                                         |
-| nxr          | does not extend to the right of, e.g. `?range=nxr.(1,10)`                                                                                                                 |
-| nxl          | does not extend to the left of                                                                                                                                            |
-| adj          | is adjacent to, e.g. `?range=adj.(1,10)`                                                                                                                                  |
-| not          | negates another operator, see [Logical operators](#logical-operators)                                                             |
-| or           | logical OR, see [Logical operators](#logical-operators)                                                                           |
-| and          | logical AND, see [Logical operators](#logical-operators)                                                                          |
-
-#### Logical operators
-
-Multiple conditions on columns are evaluated using AND by default, but you can combine them using OR with the or operator. For example, to return people under 18 or over 21:
-
-```curl
-curl "http://localhost:3000/people?or=(age.lt.18,age.gt.21)"
+### Directly Makes Connection to Database
+
+| Method                                           | Description                                                                                                                          |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `begin(String url_a, String key_a);`             | `url_a`  is a Supabase URL and `key_a` is supabase anon key. Returns `void`                                                          |
+| `login_email(String email_a, String password_a)` | Returns http response code `int`                                                                                                     |
+| `login_phone(String phone_a, String password_a)` | Returns http response code `int`                                                                                                     |
+| `insert(String table, String json, bool upsert)` | Returns http response code `int`. If you want to do upsert, set thirt parameter to `true`                                            |
+| `.doSelect()`                                    | Called at the end of select query chain, see [Examples](#examples). Returns http response payload (your data) from Supabase `String` |
+| `.doUpdate(String json)`                         | Called at the end of update query chain, see [Examples](#examples). Returns http response code from Supabase `int`                   |
+
+### Building The Queries
+
+When building the queries, you can chaining the method like this example.
+
+> Remember in `.select()` method, it is mandatory to put some low amount of `.limit()`, so you can avoid your microcontroller's memory get overflowed
+
+```arduino
+String read = db.from("table").select("*").eq("column", "value").order("column", "asc", true).limit(1).doSelect();
+```
+
+| Methods                  | Description                                                                             |
+| ------------------------ | --------------------------------------------------------------------------------------- |
+| `.from(String table);`   | Specify which table you want to query. It will append `?table_name` in Request URL      |
+| `.select(String colls);` | Specify that you want to do select query. It will append `&select=colls` in Request URL |
+| `.update(String table);` | Specify that you want to do update query. It will append `&update` in Request URL       |
+
+
+#### Horizontal Filtering (comparison) Operator
+
+| Methods                            | Description                                                                                                |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `.eq(String colls, String value)`  | Equals                                                                                                     |
+| `.gt(String colls, String value)`  | Greater than                                                                                               |
+| `.gte(String colls, String value)` | Greater than or equal                                                                                      |
+| `.lt(String colls, String value)`  | Less than                                                                                                  |
+| `.lte(String colls, String value)` | Less than or equal                                                                                         |
+| `.neq(String colls, String value)` | Not equal                                                                                                  |
+| `.in(String colls, String value)`  | One of a list of values, e.g. `1,2,3` – also supports commas in quoted strings like `"hi,there","yes,you"` |
+| `.is(String colls, String value)`  | Checking for exact equality `<null, true, false, unknown>`                                                 |
+| `.cs(String colls, String value)`  | Contains e.g. `example, new`                                                                               |
+| `.cd(String colls, String value)`  | Contained in e.g. `1, 2, 3`                                                                                |
+| `.ov(String colls, String value)`  | Overlap (have points in common), e.g. `2017-01-01, 2017-06-30`                                             |
+| `.sl(String colls, String value)`  | Strictly left of, e.g. `1,10`                                                                              |
+| `.sr(String colls, String value)`  | Strictly right of                                                                                          |
+| `.nxr(String colls, String value)` | Does not extend to the right of, e.g. `1,10`                                                               |
+| `.nxl(String colls, String value)` | Does not extend to the left of                                                                             |
+| `.adj(String colls, String value)` | Is adjacent to, e.g. `1,10`                                                                                |
+
+#### Ordering, Limiting or Offseting the Result
+
+| Methods                                       | Description                                                                                                                                                                                 |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.order(String coll, String by, bool nulls);` | This reorders the response rows. `coll` parameter is column name, `by` parameter is either `asc` or `desc`. The last parameter specifies the position of nulls, `nullsfirst` or `nullslast` |
+| `.limit(unsigned int by);`                    | Limit the amount of response rows. THIS IS MANDATORY FOR SELECT METHOD!!!                                                                                                                   |
+| `.offset(int by);`                            | Request response rows with offset is with its parameters.                                                                                                                                   |
+
+#### Getting the Query URL (for debugging)
+
+```arduino
+db.urlQuery_reset();
 ```
 
-To negate any operator, you can prefix it with not like `?a=not.eq.2` or `?not.and=(a.gte.0,a.lte.100)`.
+#### Reset the Query URL
 
-You can also apply complex logic to the conditions:
+This method calls in mandatory, must be called after one opetation (let's say `doSelect()`, or `doUpdate()`) before doing anything else.
 
-```curl
-curl "http://localhost:3000/people?grade=gte.90&student=is.true&or=(age.eq.14,not.and(age.gte.11,age.lte.17))"
+```arduino
+db.urlQuery_reset();
 ```
 
 ## To-do (sorted by priority)
 
 - [x] Make Select API (GET Request), full with row limits (one by default)
-- [ ] Make filtering query builder method in Select, Update and Delete
-- [ ] Make order/sort query builder method to in Select
-- [ ] Implement Update with PATCH HTTPS Request
-- [ ] Implement Delete with DELETE HTTPS Request
+- [x] Make filtering query builder method in Select and update
+- [x] Make order/sort query builder method to in Select
+- [x] Implement Update with PATCH HTTPS Request
 - [ ] Implement calling RPC function with HTTPS Request
 - [ ] Implement several methods to implement [Supabase Realtime](https://supabase.com/docs/guides/realtime)
+- [ ] Port to ESP8266
 
+Better documentation is always a welcoming change 😄️😄️

database-example/README.md

@@ -0,0 +1,3 @@
+## Database Playground
+
+Use this as a template to explore your supabase feature! Please make sure to enable RLS, you can enhance security with user authentication feature

examples/combined-example/combined-example.ino

@@ -6,35 +6,61 @@ Supabase db;
 
 // Put your supabase URL and Anon key here...
 // Because Login already implemented, there's no need to use secretrole key
-String supabase_url = "https://bzdazgjthqumbxiexchy.supabase.co";
-String anon_key = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImJ6ZGF6Z2p0aHF1bWJ4aWV4Y2h5Iiwicm9sZSI6ImFub24iLCJpYXQiOjE2ODExNjAwNTcsImV4cCI6MTk5NjczNjA1N30.nQb4GMqJY9DGt-i7gsd4DSSHmBwo7ucUOJHqhp5OlHE";
+String supabase_url = "";
+String anon_key = "";
 
 // put your WiFi credentials (SSID and Password) here
-const char* ssid = "FALKO 1";
-const char* psswd = "12345678";
+const char *ssid = "";
+const char *psswd = "";
 
 // Put Supabase account credentials here
-const String email = "[email protected]";
-const String password = "thisispassword";
+const String email = "";
+const String password = "";
 
-void setup() {
+
+// Put your JSON that you want to insert rows
+// You can also use library like ArduinoJson generate this
+String JSON = "";
+
+bool upsert = false;
+
+void setup()
+{
   Serial.begin(9600);
 
+  // Connecting to Wi-Fi
   Serial.print("Connecting to WiFi");
   WiFi.begin(ssid, psswd);
-  while (WiFi.status() != WL_CONNECTED) {
+  while (WiFi.status() != WL_CONNECTED)
+  {
     delay(100);
     Serial.print(".");
   }
   Serial.println("Connected!");
 
+  // Beginning Supabase Connection
   db.begin(supabase_url, anon_key);
+
+  // Logging in with your account you made in Supabase
   db.login_email(email, password);
 
-  String read = db.from("examples").select("*").eq("role","praktikan").order("date","asc", true).limit(1).doSelect();
+  // Select query with filter and order, limiting the result is mandatory here
+  String read = db.from("table").select("*").eq("column", "value").order("column", "asc", true).limit(1).doSelect();
   Serial.println(read);
+
+  // Reset Your Query before doing everything else
+  db.urlQuery_reset();
+
+  // Join operation with other table that connected via PK or FK
+  String read = db.from("table").select("*, other_table(other_table_column1, other_table_column2, another_table(*))").order("column", "asc", true).limit(1).doSelect();
+  Serial.println(read);
+  db.urlQuery_reset();
+
+  // Insert operation
+  int HTTPresponseCode = db.insert("table", JSON, upsert);
 }
 
-void loop() {
+void loop()
+{
   delay(10);
 }

examples/insert/insert.ino

@@ -17,7 +17,7 @@ void setup() {
   Serial.begin(9600);
 
   Serial.print("Connecting to WiFi");
-  WiFi.begin("Jhagas H.", "tibetanplateau");
+  WiFi.begin("ssid", "password");
   while (WiFi.status() != WL_CONNECTED) {
     delay(100);
     Serial.print(".");

examples/select/select.ino

@@ -0,0 +1,56 @@
+#include <Arduino.h>
+#include <ESP32_Supabase.h>
+#include <WiFi.h>
+
+Supabase db;
+
+// Put your supabase URL and Anon key here...
+// Because Login already implemented, there's no need to use secretrole key
+String supabase_url = "";
+String anon_key = "";
+
+// put your WiFi credentials (SSID and Password) here
+const char *ssid = "";
+const char *psswd = "";
+
+// Put Supabase account credentials here
+const String email = "";
+const String password = "";
+
+void setup()
+{
+  Serial.begin(9600);
+
+  // Connecting to Wi-Fi
+  Serial.print("Connecting to WiFi");
+  WiFi.begin(ssid, psswd);
+  while (WiFi.status() != WL_CONNECTED)
+  {
+    delay(100);
+    Serial.print(".");
+  }
+  Serial.println("Connected!");
+
+  // Beginning Supabase Connection
+  db.begin(supabase_url, anon_key);
+
+  // Logging in with your account you made in Supabase
+  db.login_email(email, password);
+
+  // Select query with filter and order, limiting the result is mandatory here
+  String read = db.from("examples").select("*").eq("column", "value").order("column", "asc", true).limit(1).doSelect();
+  Serial.println(read);
+
+  // Reset Your Query before doing everything else
+  db.urlQuery_reset();
+
+  // Join operation with other table that connected via PK or FK
+  String read = db.from("examples").select("*, other_table(other_table_column1, other_table_column2, another_table(*))").order("column", "asc", true).limit(1).doSelect();
+  Serial.println(read);
+  db.urlQuery_reset();
+}
+
+void loop()
+{
+  delay(10);
+}

examples/update/update.ino

@@ -0,0 +1,34 @@
+#include <Arduino.h>
+#include <ESP32_Supabase.h>
+#include <WiFi.h>
+
+Supabase db;
+
+// Put your target table here
+String table = "";
+
+// Put your JSON that you want to insert rows
+// You can also use library like ArduinoJson generate this
+String JSON = "";
+
+bool upsert = false;
+
+void setup() {
+  Serial.begin(9600);
+
+  Serial.print("Connecting to WiFi");
+  WiFi.begin("ssid", "password");
+  while (WiFi.status() != WL_CONNECTED) {
+    delay(100);
+    Serial.print(".");
+  }
+  Serial.println("Connected!");
+
+  int code = db.update("table").eq("column", "value").doUpdate(JSON);
+  Serial.println(code);
+  db.urlQuery_reset();
+}
+
+void loop() {
+  delay(10);
+}