Docs: update derivation concepts and samples (estuary#473)

* initial doc updates: derivations spec and TS changes

* doc npm dependencies & fix errors

* tweak flowctl subcommand

* update ts files after testing

* Add `examples` prefix to examples

* delete generated files

* Updates per review

* roll back lock file change for parity

Author: oliviamiannone

site/docs/concepts/bank/balances-test.flow.yaml

@@ -2,17 +2,17 @@ import:
   - balances.flow.yaml
 
 tests:
-  acmeBank/tests/balances:
+  examples/acmeBank/tests/balances:
     - ingest:
-        collection: acmeBank/transfers
+        collection: examples/acmeBank/transfers
         description: Initial deposits into user accounts.
         documents:
           - { id: 1, sender: CREDIT, recipient: alice, amount: 100 }
           - { id: 2, sender: CREDIT, recipient: bob, amount: 100 }
           - { id: 3, sender: CREDIT, recipient: carol, amount: 100 }
 
     - ingest:
-        collection: acmeBank/transfers
+        collection: examples/acmeBank/transfers
         description: Transfers between users, and a withdraw.
         documents:
           - { id: 4, sender: alice, recipient: bob, amount: 20 }
@@ -21,7 +21,7 @@ tests:
           - { id: 7, sender: bob, recipient: CREDIT, amount: 40 }
 
     - verify:
-        collection: acmeBank/balances
+        collection: examples/acmeBank/balances
         description: Verify expected balances.
         documents:
           - { user: CREDIT, balance: -260 }

site/docs/concepts/bank/balances.flow.ts

@@ -2,7 +2,7 @@ import:
   - transfers.flow.yaml
 
 collections:
-  acmeBank/balances:
+  examples/acmeBank/balances:
     schema:
       type: object
       required: [user]
@@ -15,9 +15,11 @@ collections:
     key: [/user]
 
     derivation:
+      typescript:
+        module: balances.ts
       transform:
         fromTransfers:
           source:
-            name: acmeBank/transfers
+            name: examples/acmeBank/transfers
           publish:
             lambda: typescript

site/docs/concepts/bank/balances.flow.yaml

@@ -0,0 +1,17 @@
+import { IDerivation, Document, Register, FromTransfersSource } from 'flow/examples/acmeBank/balances';
+
+// Implementation for derivation balances.flow.yaml#/collections/examples~1acmeBank~1balances/derivation.
+export class Derivation implements IDerivation {
+    fromTransfersPublish(
+        source: FromTransfersSource,
+        _register: Register,
+        _previous: Register,
+    ): Document[] {
+        return [
+            // Debit the sender.
+            { user: source.sender, balance: -source.amount },
+            // Credit the recipient.
+            { user: source.recipient, balance: source.amount },
+        ];
+    }
+}

site/docs/concepts/bank/balances.ts

@@ -2,9 +2,9 @@ import:
   - first-send.flow.yaml
 
 tests:
-  acmeBank/tests/first-send:
+  examples/acmeBank/tests/first-send:
     - ingest:
-        collection: acmeBank/transfers
+        collection: examples/acmeBank/transfers
         documents:
           - { id: 1, sender: alice, recipient: bob, amount: 10.25 }
           - { id: 2, sender: alice, recipient: bob, amount: 13.40 }
@@ -14,7 +14,7 @@ tests:
           - { id: 6, sender: alice, recipient: carol, amount: 7.13 }
 
     - verify:
-        collection: acmeBank/first-send
+        collection: examples/acmeBank/first-send
         description: |
           Expect we filtered to the first interaction of each account pair.
         documents:

site/docs/concepts/bank/first-send-test.flow.yaml

@@ -2,7 +2,7 @@ import:
   - transfers.flow.yaml
 
 collections:
-  acmeBank/first-send:
+  examples/acmeBank/first-send:
     schema: transfers.schema.yaml
     key: [/id]
 
@@ -13,10 +13,13 @@ collections:
         schema: { type: boolean }
         initial: false
 
+      typescript:
+        module: first-send.ts
+
       transform:
         fromTransfers:
           source:
-            name: acmeBank/transfers
+            name: examples/acmeBank/transfers
           # Shuffle so that each account pair
           # is allocated its own register.
           shuffle:

site/docs/concepts/bank/first-send.flow.ts

@@ -0,0 +1,22 @@
+import { IDerivation, Document, Register, FromTransfersSource } from 'flow/examples/acmeBank/first-send';
+
+// Implementation for derivation first-send.flow.yaml#/collections/examples~1acmeBank~1first-send/derivation.
+export class Derivation implements IDerivation {
+    fromTransfersUpdate(
+        _source: FromTransfersSource,
+    ): Register[] {
+        return [true]; // Toggle the register from `false` => `true`.
+    }
+    fromTransfersPublish(
+        source: FromTransfersSource,
+        _register: Register,
+        previous: Register,
+    ): Document[] {
+        // If the register was previously false, than this is the first
+        // transfer for this account pair.
+        if (!previous) {
+            return [source];
+        }
+        return []; // Not the first transfer.
+    }
+}

site/docs/concepts/bank/first-send.flow.yaml

@@ -2,32 +2,32 @@ import:
   - flagged-transfers.flow.yaml
 
 tests:
-  acmeBank/tests/flagged-transfers:
+  examples/acmeBank/tests/flagged-transfers:
     - ingest:
-        collection: acmeBank/transfers
+        collection: examples/acmeBank/transfers
         description: Initial deposits.
         documents:
           - { id: 1, sender: CREDIT, recipient: alice, amount: 100 }
           - { id: 2, sender: CREDIT, recipient: bob, amount: 100 }
           - { id: 3, sender: CREDIT, recipient: carol, amount: 100 }
 
     - ingest:
-        collection: acmeBank/transfers
+        collection: examples/acmeBank/transfers
         description: Transfers between users.
         documents:
           - { id: 4, sender: alice, recipient: bob, amount: 50 }
           - { id: 5, sender: bob, recipient: carol, amount: 75 }
 
     - ingest:
-        collection: acmeBank/transfers
+        collection: examples/acmeBank/transfers
         description: |
           Further transfers between users, with one being an overdraft.
         documents:
           - { id: 6, sender: alice, recipient: carol, amount: 75 }
           - { id: 7, sender: carol, recipient: bob, amount: 175 }
 
     - verify:
-        collection: acmeBank/flagged-transfers
+        collection: examples/acmeBank/flagged-transfers
         description: |
           Expect transfer #6 was flagged as being overdrawn.
         partitions: