wip

docs/intro/quickstart/index.rst

@@ -11,13 +11,10 @@ Quickstart
   setup
   modeling
   working
-  workflow
-  access
   inheritance
-  dynamic
 
 
-Welcome to the quickstart tutorial! You will create a simple Flashcards application using Next.js and Gel. The application will let users build and manage their own study decks, with each flashcard featuring customizable text on both sides - making it perfect for studying, memorization practice, or creating educational games.
+Welcome to the quickstart tutorial! In this tutorial, you will update a simple Next.js application to use Gel as your data layer. The application will let users build and manage their own study decks, with each flashcard featuring customizable text on both sides - making it perfect for studying, memorization practice, or creating educational games.
 
 Don't worry if you're new to Gel - you will be up and running with a working Next.js application and a local Gel database in just about **5 minutes**. From there, you will replace the static mock data with a Gel powered data layer in roughly 30-45 minutes.
 

docs/intro/quickstart/inheritance.rst

@@ -12,11 +12,6 @@ Adding Shared Properties
     :caption: dbschema/default.gel
 
       module default {
-        single optional global access_token: str;
-        single optional global current_user := (
-          select AccessToken filter .token = access_token
-        ).user;
-
     +   abstract type Timestamped {
     +     required created_at: datetime {
     +       default := datetime_of_statement();
@@ -26,33 +21,15 @@ Adding Shared Properties
     +     };
     +   }
     +
-    -   type User {
-    +   type User extending Timestamped {
-          required name: str;
-        }
-
-    -   type AccessToken {
-    +   type AccessToken extending Timestamped {
-          required user: User;
-          required token: str {
-            constraint exclusive;
-          };
-        }
-
     -   type Deck {
     +   type Deck extending Timestamped {
           required name: str;
           description: str;
 
-          creator: User;
-
-          cards := (select .<deck[is Card] order by .order);
-
-          access policy creator_has_full_access
-            allow all
-            using (
-              .creator ?= global current_user
-            );
+          cards := (
+            select .<deck[is Card]
+            order by .order
+          );
         };
 
     -   type Card {
@@ -62,12 +39,6 @@ Adding Shared Properties
           required back: str;
 
           required deck: Deck;
-
-          access policy deck_creator_has_full_access
-            allow all
-            using (
-              .deck.creator ?= global current_user
-            );
         }
       }
 
@@ -80,10 +51,6 @@ Adding Shared Properties
     $ npx gel migration create
     did you create object type 'default::Timestamped'? [y,n,l,c,b,s,q,?]
     > y
-    did you alter object type 'default::AccessToken'? [y,n,l,c,b,s,q,?]
-    > y
-    did you alter object type 'default::User'? [y,n,l,c,b,s,q,?]
-    > y
     did you alter object type 'default::Card'? [y,n,l,c,b,s,q,?]
     > y
     did you alter object type 'default::Deck'? [y,n,l,c,b,s,q,?]
@@ -94,6 +61,54 @@ Adding Shared Properties
     Applying m1d2m5n5ajkalyijrxdliioyginonqbtfzihvwdfdmfwodunszstya (00004-m1d2m5n.edgeql)
     ... parsed
     ... applied
+    Generating query builder...
+    Detected tsconfig.json, generating TypeScript files.
+      To override this, use the --target flag.
+      Run `npx @gel/generate --help` for full options.
+    Introspecting database schema...
+    Generating runtime spec...
+    Generating cast maps...
+    Generating scalars...
+    Generating object types...
+    Generating function types...
+    Generating operators...
+    Generating set impl...
+    Generating globals...
+    Generating index...
+    Writing files to ./dbschema/edgeql-js
+    Generation complete! 🤘
+
+.. edb:split-section::
+
+  Update the ``getDecks`` query to sort the decks by ``updated_at`` in descending order.
+
+  .. code-block:: typescript-diff
+      :caption: app/queries.ts
+
+        import { client } from "@/lib/gel";
+        import e from "@/dbschema/edgeql-js";
+
+      - const getDecksQuery = e.select(e.Deck, () => ({
+      + const getDecksQuery = e.select(e.Deck, (deck) => ({
+          id: true,
+          name: true,
+          description: true,
+          cards: {
+            id: true,
+            front: true,
+            back: true,
+          },
+      +   order_by: {
+      +     expression: deck.updated_at,
+      +     direction: e.DESC,
+      +   },
+        }));
+
+        export async function getDecks() {
+          const decks = await getDecksQuery.run(client);
+
+          return decks;
+        }
 
 .. edb:split-section::
 

docs/intro/quickstart/modeling.rst

@@ -1,31 +1,51 @@
 .. _ref_quickstart_modeling:
 
 =================
-Modeling your data
+Modeling the data
 =================
 
 .. edb:split-section::
 
   The flashcards application has a simple data model, but it's interesting enough to get a taste of many of the features of the Gel schema language. You have a ``Card`` type that describes a single flashcard, which for now contains two required string properties: ``front`` and ``back``. Each ``Card`` belongs to a ``Deck``, and there is an explicit ordering to the cards in a given deck.
 
-  Starting with this simple model, express these types in the ``default.gel`` schema file.
+  Looking at the mock data, you can see this structure in the JSON.
+
+  .. code-block:: typescript
+
+    interface Card {
+      front: string;
+      back: string;
+    }
+
+    interface Deck {
+      name: string;
+      description: string | null;
+      cards: Card[];
+    }
+
+.. edb:split-section::
+
+  Starting with this simple model, add these types to the ``default.gel`` schema file. As you can see, the types closely mirror the JSON mock data.
+
+  Also of note, the link between ``Card`` and ``Deck`` objects creates a "1-to-n" relationship, where each ``Deck`` object has a link to zero or more ``Card`` objects. When you query the ``Deck.cards`` link, the cards will be unordered, so the ``Card`` type needs an explicit ``order`` property to allow sorting them at query time.
 
   .. code-block:: sdl-diff
     :caption: dbschema/default.gel
 
       module default {
-    +   type Deck {
-    +     required name: str;
-    +     description: str;
-    +   };
-
     +   type Card {
     +     required order: int64;
     +     required front: str;
     +     required back: str;
-
-    +     required deck: Deck;
-    +   }
+    +   };
+    +
+    +   type Deck {
+    +     required name: str;
+    +     description: str;
+    +     multi cards: Card {
+    +       constraint exclusive;
+    +     };
+    +   };
       };
 
 .. edb:split-section::

docs/intro/quickstart/setup.rst

@@ -20,7 +20,7 @@ Setting up your environment
 
 .. edb:split-section::
 
-  Quickly take a poke around the empty database with the CLI REPL.
+  Explore the empty database by starting our REPL from the project root.
 
   .. code-block:: sh
 
@@ -56,12 +56,12 @@ Setting up your environment
 
 .. edb:split-section::
 
-  Fun! You will create a proper data model for the application in the next step, but for now, take a look around the project you've just created. Most of the project files will be familiar if you've worked with Next.js before. Focus on the new files that integrate Gel.
+  Fun! You will create a proper data model for the application in the next step, but for now, take a look around the project you've just created. Most of the project files will be familiar if you've worked with Next.js before. Here are the new files that integrate Gel:
 
-  - ``gel.toml``: This is the configuration file for the Gel project instance.
+  - ``gel.toml``: The configuration file for the Gel project instance.
   - ``dbschema/``: This directory contains the schema for the database, and later supporting files like migrations, and generated code.
-  - ``dbschema/default.gel``: This is the default schema file that you'll use to define your data model. It is empty for now, but you'll add your data model to this file in the next step.
-  - ``lib/gel.ts``: This file contains the Gel client, which you'll use to interact with the database.
+  - ``dbschema/default.gel``: The default schema file that you'll use to define your data model. It is empty for now, but you'll add your data model to this file in the next step.
+  - ``lib/gel.ts``: A utility module that exports the Gel client, which you'll use to interact with the database.
 
   .. code-block:: sh