docs: improve /guides/external-functions (#677)

- Improvements to the `/guides/external-functions` page.
- Adds a configuration file for git-town

#### Motivation and context

_N/A_

#### Migration notes

_N/A_

### Checklist

- [ ] The change come with new or modified tests
- [ ] Hard-to-understand functions have explanatory comments
- [ ] End-user documentation is updated to reflect the change

---------

Co-authored-by: Michaël <[email protected]>

Author: Yohe-Am

.git-branches.toml

@@ -0,0 +1,19 @@
+push-hook = true
+push-new-branches = false
+ship-delete-tracking-branch = false
+sync-before-ship = true
+sync-upstream = true
+
+[branches]
+main = "main"
+perennials = []
+perennial-regex = ""
+
+[hosting]
+# platform = ""
+# origin-hostname = ""
+
+[sync-strategy]
+
+feature-branches = "rebase"
+perennial-branches = "rebase"

.gitignore

@@ -45,3 +45,5 @@ typegraph/node/sdk/src/gen
 typegraph/python/typegraph/gen
 
 *.egg-info/
+
+examples/typegraphs/migrations

examples/metatype.yaml

@@ -12,7 +12,7 @@ typegates:
         GITHUB_CLIENT_ID: fake
         GITHUB_CLIENT_SECRET: fake
       authentication:
-        BASIC_ADMIN: "password"
+        BASIC_andim: "password"
       docs:
         SENDINBLUE_KEY: "fake"
       homepage:
@@ -26,8 +26,8 @@ typegates:
       database:
         POSTGRES_CONN: "postgresql://postgres:password@localhost:5432/db?schema=database"
       policies:
-        BASIC_ADMIN: "admin_pass"
-        BASIC_USER: "user_pass"
+        BASIC_admin: "admin_pass"
+        BASIC_user: "user_pass"
       auth:
         CUSTOM_JWT: "mysupersecretkey"
       graphql:
@@ -41,7 +41,7 @@ typegates:
       iam-provider:
         GITHUB_CLIENT_ID: "fake"
         GITHUB_CLIENT_SECRET: "fake"
-      retrend:
+      files-upload:
         S3_HOST: http://localhost:9000
         S3_REGION: local
         S3_ACCESS_KEY: minio
@@ -66,6 +66,8 @@ typegates:
         BASIC_ADMIN: hunter2
       roadmap:
         BASIC_ADMIN: hunter2
+      func-gql:
+        POSTGRES: "postgresql://postgres:password@localhost:5432/db?schema=func_ctx"
 
   prd:
     url: https://demo.metatype.dev
@@ -80,7 +82,7 @@ typegates:
         GITHUB_CLIENT_ID: infisical://app.infisical.com/643057c5bb17b13ef6e73d99/prod/GITHUB_CLIENT_ID
         GITHUB_CLIENT_SECRET: infisical://app.infisical.com/643057c5bb17b13ef6e73d99/prod/GITHUB_CLIENT_SECRET
       authentication:
-        BASIC_ADMIN: "password"
+        BASIC_andim: "password"
       docs:
         SENDINBLUE_KEY: infisical://app.infisical.com/643057c5bb17b13ef6e73d99/prod/TG_DOCS_SENDINBLUE_KEY
       homepage:
@@ -94,8 +96,8 @@ typegates:
       database:
         POSTGRES_CONN: infisical://app.infisical.com/643057c5bb17b13ef6e73d99/prod/TG_DATABASE_POSTGRES_CONN
       policies:
-        BASIC_ADMIN: "admin_pass"
-        BASIC_USER: "user_pass"
+        BASIC_admin: "admin_pass"
+        BASIC_user: "user_pass"
       auth:
         CUSTOM_JWT: "mysupersecretkey"
       graphql:
@@ -109,7 +111,7 @@ typegates:
       iam-provider:
         GITHUB_CLIENT_ID: infisical://app.infisical.com/643057c5bb17b13ef6e73d99/prod/GITHUB_CLIENT_ID
         GITHUB_CLIENT_SECRET: infisical://app.infisical.com/643057c5bb17b13ef6e73d99/prod/GITHUB_CLIENT_SECRET
-      retrend:
+      files-upload:
         S3_HOST: http://localhost:9000
         S3_REGION: local
         S3_ACCESS_KEY: minio
@@ -139,3 +141,7 @@ typegraphs:
   materializers:
     prisma:
       migrations_path: "migrations"
+
+metagen:
+  targets:
+    main:

examples/typegraphs/authentication.py

@@ -3,33 +3,32 @@
 from typegraph.graph.params import Auth, Cors
 from typegraph.runtimes.deno import DenoRuntime
 
-# skip:end
-
 
 @typegraph(
-    # skip:start
     cors=Cors(allow_origin=["https://metatype.dev", "http://localhost:3000"]),
-    # skip:end
-    # ..
 )
 def authentication(g: Graph):
+    # skip:end
     deno = DenoRuntime()
-    public = Policy.public()
-
     ctx = t.struct({"username": t.string().optional()})
 
     # highlight-start
     # expects a secret in metatype.yml
     # `BASIC_[username]`
     # highlight-next-line
-    g.auth(Auth.basic(["admin"]))
+    g.auth(Auth.basic(["andim"]))
     # highlight-end
 
     g.expose(
+        Policy.public(),
         get_context=deno.identity(ctx).apply(
             {
                 "username": g.from_context("username"),
             }
         ),
-        default_policy=[public],
+        get_full_context=deno.func(
+            t.struct({}),
+            t.string(),
+            code="(_: any, ctx: any) => Deno.inspect(ctx.context)",
+        ),
     )

examples/typegraphs/authentication.ts

@@ -3,15 +3,12 @@ import { Policy, t, typegraph } from "@typegraph/sdk/index.js";
 import { Auth } from "@typegraph/sdk/params.js";
 import { DenoRuntime } from "@typegraph/sdk/runtimes/deno.js";
 
-// skip:end
-
 await typegraph({
   name: "authentication",
-  // skip:next-line
   cors: { allowOrigin: ["https://metatype.dev", "http://localhost:3000"] },
 }, (g) => {
+  // skip:end
   const deno = new DenoRuntime();
-  const pub = Policy.public();
 
   const ctx = t.struct({
     "username": t.string().optional(),
@@ -21,12 +18,21 @@ await typegraph({
   // expects a secret in metatype.yml
   // `BASIC_[username]`
   // highlight-next-line
-  g.auth(Auth.basic(["admin"]));
+  g.auth(Auth.basic(["andim"]));
   // highlight-end
 
   g.expose({
     get_context: deno.identity(ctx).apply({
       username: g.fromContext("username"),
-    }).withPolicy(pub),
-  });
+    }),
+    get_full_context: deno.func(
+      t.struct({}),
+      t.string(),
+      {
+        code: "(_: any, ctx: any) => Deno.inspect(ctx.context)",
+      },
+    ),
+  }, Policy.public());
+  // skip:start
 });
+// skip:end

examples/typegraphs/cors.py

@@ -6,26 +6,20 @@
 
 # skip:end
 @typegraph(
-    # highlight-next-line
+    # highlight-start
     cors=Cors(
-        # highlight-next-line
         allow_origin=["https://not-this.domain"],
-        # highlight-next-line
         allow_headers=["x-custom-header"],
-        # highlight-next-line
         expose_headers=["header-1"],
-        # highlight-next-line
         allow_credentials=True,
-        # highlight-next-line
         max_age_sec=60,
-        # highlight-next-line
     ),
+    # highlight-end
 )
-def auth(g: Graph):
+def cors(g: Graph):
     random = RandomRuntime(seed=0, reset=None)
-    public = Policy.public()
 
     g.expose(
-        public,
+        Policy.public(),
         catch_me_if_you_can=random.gen(t.string()),
     )

examples/typegraphs/cors.ts

@@ -5,25 +5,20 @@ import { RandomRuntime } from "@typegraph/sdk/runtimes/random.js";
 // skip:end
 
 await typegraph({
-  name: "auth",
-  // highlight-next-line
+  name: "cors",
+  // highlight-start
   cors: {
-    // highlight-next-line
     allowOrigin: ["https://not-this.domain"],
-    // highlight-next-line
     allowHeaders: ["x-custom-header"],
-    // highlight-next-line
     exposeHeaders: ["header-1"],
-    // highlight-next-line
     allowCredentials: true,
-    // highlight-next-line
     maxAgeSec: 60,
   },
+  // highlight-end
 }, (g) => {
   const random = new RandomRuntime({ seed: 0 });
-  const pub = Policy.public();
 
   g.expose({
-    catch_me_if_you_can: random.gen(t.string()).withPolicy(pub),
-  });
+    catch_me_if_you_can: random.gen(t.string()),
+  }, Policy.public());
 });

examples/typegraphs/example_rest.py

@@ -1,3 +1,4 @@
+# skip:start
 from typegraph import Graph, Policy, t, typegraph
 from typegraph.runtimes.deno import DenoRuntime
 
@@ -16,9 +17,18 @@ def example_rest(g: Graph):
         },
         name="Post",
     )
+    # skip:end
+
+    g.expose(
+        postFromUser=deno.func(
+            user,
+            post,
+            code="(_) => ({ id: 12, author: {id: 1}  })",
+        ).with_policy(pub),
+    )
 
-    # API docs {typegate_url}/example-rest/rest
     # In this example, the query below maps to {typegate_url}/example-rest/rest/get_post?id=..
+    # highlight-start
     g.rest(
         """
         query get_post($id: Integer) {
@@ -31,11 +41,4 @@ def example_rest(g: Graph):
         }
         """
     )
-
-    g.expose(
-        postFromUser=deno.func(
-            user,
-            post,
-            code="(_) => ({ id: 12, author: {id: 1}  })",
-        ).with_policy(pub),
-    )
+    # highlight-end

examples/typegraphs/example_rest.ts

@@ -1,3 +1,4 @@
+// skip:start
 import { Policy, t, typegraph } from "@typegraph/sdk/index.js";
 import { DenoRuntime } from "@typegraph/sdk/runtimes/deno.js";
 
@@ -17,9 +18,18 @@ await typegraph({
     },
     { name: "Post" },
   );
+  //  skip:end
+
+  g.expose({
+    postFromUser: deno.func(
+      user,
+      post,
+      { code: "(_) => ({ id: 12, author: {id: 1}  })" },
+    ).withPolicy(pub),
+  });
 
-  // API docs {typegate_url}/example-rest/rest
   // In this example, the query below maps to {typegate_url}/example-rest/rest/get_post?id=..
+  // highlight-start
   g.rest(
     `
         query get_post($id: Integer) {
@@ -32,12 +42,6 @@ await typegraph({
         }
     `,
   );
-
-  g.expose({
-    postFromUser: deno.func(
-      user,
-      post,
-      { code: "(_) => ({ id: 12, author: {id: 1}  })" },
-    ).withPolicy(pub),
-  });
+  // highlight-end
+  // skip:start
 });

examples/typegraphs/files-upload.py

@@ -6,12 +6,11 @@
 
 
 @typegraph(
+    name="files-upload",
     # skip-next-line
     cors=Cors(allow_origin=["https://metatype.dev", "http://localhost:3000"]),
 )
-def retrend(g: Graph):
-    public = Policy.public()
-
+def files_upload(g: Graph):
     s3 = S3Runtime(
         # we provide the name of the env vars
         # the typegate will read from
@@ -23,11 +22,11 @@ def retrend(g: Graph):
     )
 
     g.expose(
+        Policy.public(),
         # we can then generate helpers for interacting with our runtime
         listObjects=s3.list("bucket"),
         getDownloadUrl=s3.presign_get("bucket"),
         signUploadUrl=s3.presign_put("bucket"),
         upload=s3.upload("bucket", t.file(allow=["image/png", "image/jpeg"])),
         uploadMany=s3.upload_all("bucket"),
-        default_policy=[public],
     )

examples/typegraphs/files-upload.ts

@@ -2,12 +2,10 @@ import { Policy, t, typegraph } from "@typegraph/sdk/index.js";
 import { S3Runtime } from "@typegraph/sdk/providers/aws.js";
 
 await typegraph({
-  name: "retrend",
+  name: "files-upload",
   // skip:next-line
   cors: { allowOrigin: ["https://metatype.dev", "http://localhost:3000"] },
 }, (g) => {
-  const pub = Policy.public();
-
   const s3 = new S3Runtime({
     hostSecret: "S3_HOST",
     regionSecret: "S3_REGION",
@@ -22,5 +20,5 @@ await typegraph({
     signUploadUrl: s3.presignPut({ bucket: "bucket" }),
     upload: s3.upload("bucket", t.file({ allow: ["image/png", "image/jpeg"] })),
     uploadMany: s3.uploadAll("bucket"),
-  }, pub);
+  }, Policy.public());
 });