Merge branch 'main' into upload/s3

Author: destifo

examples/typegraphs/http-runtime.py

@@ -0,0 +1,44 @@
+# skip:start
+from typegraph import typegraph, Policy, t, Graph
+from typegraph.graph.params import Cors
+from typegraph.runtimes import HttpRuntime
+
+
+# skip:end
+@typegraph(
+    # skip:next-line
+    cors=Cors(allow_origin=["https://metatype.dev", "http://localhost:3000"]),
+)
+def http_example(g: Graph):
+    pub = Policy.public()
+
+    facts = HttpRuntime("https://uselessfacts.jsph.pl/api/v2/facts")
+
+    g.expose(
+        pub,
+        facts=facts.get(
+            "/random",
+            t.struct({"language": t.enum(["en", "de"])}),
+            t.struct(
+                {
+                    "id": t.string(),
+                    "text": t.string(),
+                    "source": t.string(),
+                    "source_url": t.string(),
+                    "language": t.string(),
+                    "permalink": t.string(),
+                }
+            ),
+        ),
+        facts_as_text=facts.get(
+            "/random",
+            t.struct(
+                {
+                    "header_accept": t.string().set("text/plain"),
+                    "language": t.enum(["en", "de"]),
+                }
+            ),
+            t.string(),
+            header_prefix="header_",
+        ),
+    )

examples/typegraphs/random-field.py

@@ -0,0 +1,44 @@
+from typegraph import typegraph, Policy, t, Graph
+from typegraph.runtimes.deno import DenoRuntime
+
+# skip:start
+from typegraph.graph.params import Cors
+
+# skip:end
+import time
+
+
+@typegraph(
+    # skip:start
+    cors=Cors(allow_origin=["https://metatype.dev", "http://localhost:3000"]),
+    name="random-field",
+    # skip:end
+)
+def roadmap(g: Graph):
+    deno = DenoRuntime()
+    pub = Policy.public()
+
+    bonus = t.list(t.enum(["+1 gold", "+1 metal"]))
+    daily_bonus = t.struct(
+        {
+            "performance": t.integer(),
+            "bonus": bonus.from_random(),  # this field is now generated randomly
+        }
+    )
+
+    # set a custom seed
+    custom = int(round(time.time() * 1000)) % 1000
+    g.configure_random_injection(seed=custom)
+
+    g.expose(
+        pub,
+        get_bonus=deno.func(
+            daily_bonus,
+            t.string(),
+            code="""
+            ({ performance, bonus }) => `Daily bonus: ${
+                (performance > 100 ? bonus : ['none']).join(', ')
+            }`;
+            """,
+        ),
+    )

examples/typegraphs/roadmap-random.py

@@ -1,6 +1,9 @@
 from typegraph import typegraph, Policy, t, Graph
 from typegraph.runtimes.random import RandomRuntime
+
+# skip:start
 from typegraph.graph.params import Cors
+# skip:end
 
 
 @typegraph(
@@ -10,21 +13,13 @@
     # skip:end
 )
 def roadmap(g: Graph):
+    # skip:start
     _bucket = t.struct(
         {
             "id": t.integer(as_id=True),
             "name": t.string(),
         }
     )
-    idea = t.struct(
-        {
-            "id": t.uuid(
-                as_id=True
-            ),  # email is just a shorthand alias for `t.string({format: "uuid"})`
-            "name": t.string(),
-            "authorEmail": t.email(),  # another string shorthand
-        }
-    )
     _vote = t.struct(
         {
             "id": t.uuid(),
@@ -36,6 +31,16 @@ def roadmap(g: Graph):
             "desc": t.string().optional(),  # makes it optional
         }
     )
-    random = RandomRuntime(reset=None)
+    # skip:end
+    idea = t.struct(
+        {
+            "id": t.uuid(
+                as_id=True
+            ),  # uuid is just a shorthand alias for `t.string({format: "uuid"})`
+            "name": t.string(),
+            "authorEmail": t.email(),  # another string shorthand
+        }
+    )
+    random = RandomRuntime(reset=None, seed=1)
     pub = Policy.public()
     g.expose(pub, get_idea=random.gen(idea))

examples/typegraphs/roadmap-random.ts

@@ -9,21 +9,13 @@ await typegraph({
   // skip:next-line
   cors: { allowOrigin: ["https://metatype.dev", "http://localhost:3000"] },
 }, (g) => {
+  // skip:start
   const _bucket = t.struct(
     {
       "id": t.integer({}, { asId: true }),
       "name": t.string(),
     },
   );
-
-  const idea = t.struct(
-    {
-      "id": t.uuid({ asId: true }), // email is just a shorthand alias for `t.string({}, {{format: "uuid"}: undefined})`
-      "name": t.string(),
-      "authorEmail": t.email(), // another string shorthand
-    },
-  );
-
   const _vote = t.struct(
     {
       "id": t.uuid(),
@@ -35,8 +27,17 @@ await typegraph({
       "desc": t.string().optional(), // makes it optional
     },
   );
+  // skip:end
+
+  const idea = t.struct(
+    {
+      "id": t.uuid({ asId: true }), // uuid is just a shorthand alias for `t.string({}, {{format: "uuid"}: undefined})`
+      "name": t.string(),
+      "authorEmail": t.email(), // another string shorthand
+    },
+  );
 
-  const random = new RandomRuntime({});
+  const random = new RandomRuntime({ seed: 1 });
   const pub = Policy.public();
   g.expose({ get_idea: random.gen(idea) }, pub);
 });

website/docs/concepts/features-overview/index.mdx

@@ -51,5 +51,5 @@ Working with object files in Metatype is easy using the [S3Runtime](/docs/refere
 
 ## Function runner
 
-When the expressive powers of the typegate primitives are not up for the task, different runtimes are available for running the exact, turing complete, code you need.
-Metatype supports [Typescript](/docs/reference/runtimes/deno), [Python](/docs/reference/runtimes/python) and [Wasm](/docs/reference/runtimes/wasmedge) functions today.
+When the expressive powers of the typegate primitives are not up for the task, different runtimes are available for running the exact, turing complete, code you need. 
+Metatype supports [Typescript](/docs/reference/runtimes/deno), [Python](/docs/reference/runtimes/python) and [Wasm](/docs/reference/runtimes/wasm) functions today.

website/docs/reference/meta-cli/available-commands.mdx

@@ -0,0 +1,27 @@
+# Available commands
+
+## Managing typegraphs
+
+| Command  |                                                                Example of use                                                                 |                       Description                        |
+| -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| deploy   | <pre><p>meta deploy --target dev --file path/to/typegraph.py</p><p>meta --dir folder/to/typegraphs dev --run-destructive-migrations</p></pre> | Deploy typegraph to a typegate instance                  |
+| undeploy | <pre><p>meta undeploy --target dev --typegraph logs accounting services</p></pre>                                                             | Undeploy typegraphs by name                              |
+| gen      | <pre><p>meta gen mod --file path/to/typegraph.py</p><p></p>meta gen mdk</pre>                                                                 | Generate script or files that are used in your typegraph |
+| typegate | <pre><p>meta typegate --quiet</p></pre>                                                                                                       | Access a minimal deno CLI                                |
+
+## Troubleshooting and others
+
+|  Command   |                            Example of use                            |                               Description                                |
+| ---------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| doctor     | <pre><p>meta doctor</p></pre>                                        | Help troubleshoot all your installations                                 |
+| completion | <pre><p>meta completion</p><p>meta completion --shell bash</p></pre> | Generate shell completion (supports bash, elvish, fish, powershell, zsh) |
+| serialize  | <pre><p>meta serialize --file path/to/typegraph.py</p></pre>        | Inspect serialized version of your typegraph                             |
+| upgrade    | <pre><p>meta upgrade</p><p>meta upgrade --version 0.3.4</p></pre>    | Upgrade current cli                                                      |
+
+
+Feel free to use the `--help` flag if you want more informations on each commands/subcommands.
+```bash
+meta -h
+meta deploy -h
+meta gen mod -h
+```

website/docs/reference/meta-cli/index.mdx

@@ -22,7 +22,7 @@ It deploy your typegraph to the Metatype Cloud or your self-hosted typegate inst
 
 ## Development typegate
 
-For development purposes, the cli bundles the typegate itself and this can be accessed throug the `meta typegate` subcommand.
+For development purposes, the cli bundles the typegate itself and this can be accessed through the `meta typegate` subcommand.
 
 :::info
 

website/docs/reference/runtimes/graphql/index.mdx

@@ -4,7 +4,7 @@ import TGExample from "@site/src/components/TGExample";
 
 ## GraphQL runtime
 
-You currently have a single model to describe messages sent in the chat-based app. A reasonable next step is to add a user model and make a link between the two. While you can store users in the same database, it's wiser to avoid data duplication and re-use your service for user management available at [GraphQLZero](https://graphqlzero.almansi.me) endpoint. Let's introduce the GraphQL runtime that allows remote GraphQL queries.
+You currently have a single model to describe messages sent in the chat-based app. A reasonable next step is to add a user model and make a link between the two. While you can store users in the same database, it's wiser to avoid data duplication and re-use your service for user management available at [GraphQLZero](https://graphqlzero.almansi.me) endpoint. Let's introduce the [GraphQL](https://spec.graphql.org/October2021/) runtime that allows remote GraphQL queries.
 
 Update `typegraph.py` with the highlighted lines below:
 

website/docs/reference/runtimes/http/http.graphql

@@ -0,0 +1,9 @@
+query {
+    facts(language: "en") {
+        id
+        text
+        # source_url
+        # permalink
+    }
+    facts_as_text(language: "en")
+}

website/docs/reference/runtimes/http/index.mdx

@@ -1,18 +1,102 @@
+import TGExample from "@site/src/components/TGExample";
+import SDKTabs from "@site/src/components/SDKTabs";
+import TabItem from "@theme/TabItem";
+
 # HTTP/REST 
 
-The HTTPRuntime allows our typegraphs to access external REST APIs.
+## HTTP Runtime
+The HTTPRuntime allows your typegraphs to access external REST APIs.
+
+Common use cases (but not limited to):
+- Enable consuming one or more REST APIs through the same interface
+- Programmatically generate typegraphs from an existing [openapi specs](https://swagger.io/specification/) or similar
 
 Example:
+<TGExample
+    typegraph="http-runtime"
+    python={require("../../../../../examples/typegraphs/http-runtime.py")}
+    query={require("./http.graphql")}
+/>
 
-```python
-from typegraph.runtime.http import HTTPRuntime
 
-# ..
+## Verbs
+This runtime supports `GET`, `POST`, `PUT`, `DELETE` http verbs.
+
+In most cases, queries are not limited to a simple query parameter or use the default `application/json` content type. 
+You can assign what parts of your request description each field in the input struct belongs to.
+
+In the example bellow, this endpoint corresponds to `POST <API_URL>/submit_user?form_type=..` with a body requiring the fields:
+`pseudo`, `age` and with header `accept` set as `application/json`.
 
-remote = HTTPRuntime('https://dev.to/api')
-remote.get(
-    '/test',
-    t.struct({}),
-    t.list(t.struct({'a': t.integer()})),
-)
+
+<SDKTabs>
+    <TabItem value="python">
+```python
+# ..
+    remote = HTTPRuntime("<API_URL>")
+    g.expose(
+        pub,
+        add_user=remote.post(
+            "/submit_user",
+            # define your input/output
+            t.struct(
+                {
+                    "id": t.uuid(),
+                    "username": t.float(),
+                    "years_lived": t.integer(),
+                    "form_type": t.integer(),
+                    "config_accept": t.string().set("application/json")
+                },
+            ),
+            t.struct({ "message": t.string() }),
+            # specify where each field in your input should be associated with
+            body_fields=("username", "years_lived"),
+            query_fields=("form_type"),
+            # you may want to rename a few fields
+            # if you are using your own naming conventions or reusing types
+            rename_fields={
+                "username": "pseudo",
+                "years_lived": "age",
+            },
+            content_type="multipart/form-data",
+            # set a custom header prefix
+            header_prefix="config_"
+        )
+    )
+# ..
+```
+    </TabItem>
+    <TabItem value="typescript">
+```typescript
+// ..
+  const remote = new HttpRuntime("<API_URL>");
+  g.expose({
+    add_user: remote.post(
+      // define your input/output
+      t.struct(
+        {
+          id: t.uuid(),
+          username: t.float(),
+          years_lived: t.integer(),
+          form_type: t.integer()
+        },
+      ),
+      t.struct({ message: t.string() }),
+      {
+        path: "/submit_user",
+        // specify where each field in your input should be associated with
+        bodyFields: ["username", "years_lived"],
+        queryFields: ["form_type"],
+        // you may want to rename a few fields
+        // if you are using your own naming conventions or reusing types
+        renameFields: [
+          ["username", "pseudo"],
+          ["years_lived", "age"],
+        ],
+        contentType: "multipart/form-data",
+      }
+  )}, pub);
+// ..
 ```
+    </TabItem>
+</SDKTabs>