feat(sdk): reusable import module (#970)

<!--
Pull requests are squashed and merged using:
- their title as the commit message
- their description as the commit body

Having a good title and description is important for the users to get
readable changelog.
-->

<!-- 1. Explain WHAT the change is about -->

- Closes
[MET-819](https://linear.app/metatypedev/issue/MET-819/automated-typegraph-artifact-deps).

Example:

```typescript
import { Policy, t, typegraph } from "@typegraph/sdk";
import { DenoRuntime, DenoModule } from "@typegraph/sdk/runtimes/deno";

await typegraph({ name: "multi_import" }, (g) => {
    const deno = new DenoRuntime();
    const pub = Policy.public();

    const mod = new DenoModule({
      path: "ops.ts",
      deps: ["dep.ts"],
      exports: ["add", "sub"], // for type hints
    });

    g.expose({
      add: deno
        .import(t.struct({ a: t.float(), b: t.float() }), t.float(), {
          module: mod.import("add"),
        })
        .withPolicy(pub),
      sub: deno
        .import(t.struct({ a: t.float(), b: t.float() }), t.float(), {
          module: mod.import("sub"),
        })
        .withPolicy(pub),
    });
  },
);
```

<!-- 3. Explain HOW users should update their code -->

#### Migration notes

---

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


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

## Summary by CodeRabbit

- **New Features**
	- Enhanced module import functionality for Deno and Python runtimes.
- Introduced `DenoModule` and `PythonModule` for improved module
configuration.
- Added new examples demonstrating TypeScript and Python integration
using Deno.

- **Improvements**
	- Streamlined import methods with more robust parameter handling.
- Added type safety and more precise type definitions for module
parameters.
	- Simplified module import and dependency specification.

- **Technical Updates**
	- Updated runtime import methods with additional parameters.
	- Introduced new utility functions for module parameter resolution.
	- Refined type aliases and interfaces for module imports.
	- Expanded test coverage to include new typegraph files.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: luckasRanarison

docs/metatype.dev/docs/reference/runtimes/deno/index.mdx

@@ -14,34 +14,19 @@ The DenoRuntime allows you to run lightweight and short-lived typescript functio
   query={require("./deno.graphql")}
 />
 
-Instead of providing the typescript code inline, we can also point to a file on disk:
-
-```python
-# my_typegraph.py
-
-from typegraph import typegraph, Policy, t, Graph
-from typegraph.runtimes.deno import DenoRuntime
-
-@typegraph()
-def deno(g: Graph):
-    public = Policy.public()
-    deno = DenoRuntime()
-
-    g.expose(
-        public,
-        add=deno.import_(
-            t.struct({"a": t.number(), "b": t.number()}),
-            t.number(),
-            module="main.ts", # path to ts file
-            name="doAddition", # function export from ts file to use
-        ),
-    )
-```
+Instead of providing the typescript code inline, we can also point to a local file:
+
+<TGExample
+  typegraph="deno"
+  typescript={require("!!code-loader!../../../../../../examples/typegraphs/deno-import.ts")}
+  python={require("!!code-loader!../../../../../../examples/typegraphs/deno-import.py")}
+  disablePlayground={true}
+/>
 
-Where main.ts looks like:
+Where ops.ts looks like:
 
 ```typescript
-// main.ts
+// ops.ts
 
 interface AddInput {
   a: number;

docs/metatype.dev/docs/reference/runtimes/python/index.mdx

@@ -1,37 +1,20 @@
 # Python
 
+import CodeBlock from "@theme/CodeBlock";
+import TGExample from "@site/src/components/TGExample";
+
 ## Python Runtime
 
 The PythonRuntime allows you to run short-lived code on a Python virtual machine.
 
-```python
-# my_typegraph.py
-
-from typegraph import typegraph, Policy, t, Graph
-from typegraph.runtimes.deno import PythonRuntime
+<TGExample
+  typegraph="deno"
+  typescript={require("!!code-loader!../../../../../../examples/typegraphs/python.ts")}
+  python={require("!!code-loader!../../../../../../examples/typegraphs/python.py")}
+  disablePlayground={true}
+/>
 
-@typegraph()
-def example_python(g: Graph):
-    public = Policy.public()
-    python = PythonRuntime()
-
-    g.expose(
-        public,
-        add=t.func(
-            t.struct({"a": t.integer(), "b": t.integer()}),
-            t.integer(),
-            # we can provide the code inline using lambdas
-            python.from_lambda(lambda x: x["a"] + x["b"]),
-        ),
-        sayHello=python.import_(
-            t.struct({"name": t.string()}),
-            t.string(),
-            # point to pythoin a file on disc
-            module="hello.py",
-            name="say_hello"
-        ),
-    )
-```
+Where hello.py looks like:
 
 ```python
 # hello.py

examples/typegraphs/deno-import.py

@@ -0,0 +1,37 @@
+# skip:start
+from typegraph import typegraph, Policy, t, Graph
+from typegraph.runtimes.deno import DenoRuntime, DenoModule
+
+# skip:end
+
+
+@typegraph()
+def deno_import(g: Graph):
+    public = Policy.public()
+    deno = DenoRuntime()
+
+    g.expose(
+        public,
+        add=deno.import_(
+            t.struct({"a": t.integer(), "b": t.integer()}),
+            t.integer(),
+            module="./scripts/ops.ts",  # path to ts file
+            name="doAddition",  # function export from ts file to use
+            # deps=[], path to dependencies
+        ),
+    )
+
+    # We can also use the following method for reusability
+    module = DenoModule(
+        path="./scripts/ops.ts",
+        deps=["./scripts/deps.ts"],
+    )
+
+    g.expose(
+        public,
+        add_alt=deno.import_(
+            t.struct({"a": t.integer(), "b": t.integer()}),
+            t.integer(),
+            module=module.import_("doAddition"),  # name of the function to use
+        ),
+    )

examples/typegraphs/deno-import.ts

@@ -0,0 +1,47 @@
+// skip:start
+import { Policy, t, typegraph } from "@typegraph/sdk";
+import { DenoModule, DenoRuntime } from "@typegraph/sdk/runtimes/deno";
+
+// skip:end
+
+await typegraph(
+  {
+    name: "deno-import",
+  },
+  (g) => {
+    const deno = new DenoRuntime();
+    const pub = Policy.public();
+
+    g.expose(
+      {
+        add: deno.import(
+          t.struct({ a: t.integer(), b: t.integer() }),
+          t.integer(),
+          {
+            module: "./scripts/ops.ts", // path to ts file
+            name: "doAddition", // function export to use
+            // deps: [], path to dependecies
+          },
+        ),
+      },
+      pub,
+    );
+
+    // We can also use the following method for reusability
+    const mod = new DenoModule({
+      path: "./scripts/ops.ts",
+      deps: ["./scripts/deps.ts"],
+    });
+
+    g.expose(
+      {
+        add_alt: deno.import(
+          t.struct({ a: t.integer(), b: t.integer() }),
+          t.integer(),
+          { module: mod.import("doAddition") }, // name of the function to use
+        ),
+      },
+      pub,
+    );
+  },
+);

examples/typegraphs/python.py

@@ -0,0 +1,38 @@
+from typegraph import typegraph, Policy, t, Graph
+from typegraph.runtimes.python import PythonRuntime, PythonModule
+
+
+@typegraph()
+def python(g: Graph):
+    public = Policy.public()
+    python = PythonRuntime()
+
+    g.expose(
+        public,
+        add=python.from_lambda(
+            t.struct({"a": t.integer(), "b": t.integer()}),
+            t.integer(),
+            # we can provide the code inline using lambdas
+            function=lambda x: x["a"] + x["b"],
+        ),
+        sayHello=python.import_(
+            t.struct({"name": t.string()}),
+            t.string(),
+            # point to a local python file
+            module="./scripts/hello.py",
+            name="say_hello",  # name of the function to use
+            # deps=["deps.py"], path to dependencies
+        ),
+    )
+
+    # We can also use the following method for reusability
+    module = PythonModule(path="./scripts/hello.py", deps=["./scripts/deps.py"])
+
+    g.expose(
+        public,
+        sayHelloAlt=python.import_(
+            t.struct({"name": t.string()}),
+            t.string(),
+            module=module.import_("say_hello"),  # name of the function to use
+        ),
+    )

examples/typegraphs/python.ts

@@ -0,0 +1,52 @@
+// skip:start
+import { Policy, t, typegraph } from "@typegraph/sdk";
+import { PythonModule, PythonRuntime } from "@typegraph/sdk/runtimes/python";
+
+// skip:end
+
+await typegraph(
+  {
+    name: "python",
+  },
+  (g) => {
+    const python = new PythonRuntime();
+    const pub = Policy.public();
+
+    g.expose(
+      {
+        add: python.fromLambda(
+          t.struct({ a: t.integer(), b: t.integer() }),
+          t.integer(),
+          // we can provide the code inline using lambdas
+          { code: "lambda x: (x['a'] + x['b'])" },
+        ),
+        sayHello: python.import(
+          t.struct({ name: t.string() }),
+          t.string(),
+          // point to a local python file
+          {
+            module: "./scripts/hello.py",
+            name: "say_hello", // name of the function to use
+            // deps: ["deps.py"], path to dependencies
+          },
+        ),
+      },
+      pub,
+    );
+
+    // We can also use the following method for reusability
+    const mod = new PythonModule({
+      path: "./scripts/hello.py",
+      deps: ["./scripts/deps.py"],
+    });
+
+    g.expose(
+      {
+        sayHelloAlt: python.import(t.struct({ name: t.string() }), t.string(), {
+          module: mod.import("say_hello"), // name of the function to use
+        }),
+      },
+      pub,
+    );
+  },
+);

examples/typegraphs/scripts/deps.py

@@ -0,0 +1,2 @@
+def say_hello(x: any):
+    return f"Hello {x["name"]}"

examples/typegraphs/scripts/deps.ts

@@ -0,0 +1,7 @@
+interface AddInput {
+  a: number;
+  b: number;
+}
+export function doAddition({ a, b }: AddInput) {
+  return a + b;
+}

examples/typegraphs/scripts/hello.py

@@ -7,6 +7,13 @@ import type { Effect } from "../gen/typegraph_core.d.ts";
 import Policy from "../policy.ts";
 import { type Materializer, Runtime } from "./mod.ts";
 import { fx } from "../index.ts";
+import {
+  type ModuleImport,
+  type ModuleImportPolicy,
+  resolveModuleParams,
+} from "../utils/module.ts";
+
+export { Module as DenoModule } from "../utils/module.ts";
 
 interface FunMat extends Materializer {
   code: string;
@@ -32,13 +39,7 @@ export interface DenoFunc {
   effect?: Effect;
 }
 
-export interface DenoImport {
-  name: string;
-  module: string;
-  deps?: Array<string>;
-  secrets?: Array<string>;
-  effect?: Effect;
-}
+type DenoImport = ModuleImport;
 
 // deno-lint-ignore no-explicit-any
 function stringifyFn(code: string | ((...any: []) => any)) {
@@ -85,21 +86,20 @@ export class DenoRuntime extends Runtime {
   import<I extends t.Typedef = t.Typedef, O extends t.Typedef = t.Typedef>(
     inp: I,
     out: O,
-    { name, module, deps = [], effect = fx.read(), secrets = [] }: DenoImport,
+    { effect = fx.read(), secrets = [], ...params }: DenoImport,
   ): t.Func<I, O, ImportMat> {
+    const resolved = resolveModuleParams(params);
     const matId = runtimes.importDenoFunction(
       {
-        funcName: name,
-        module,
-        deps,
         secrets,
+        ...resolved,
       },
       effect,
     );
     const mat: ImportMat = {
       _id: matId,
-      name,
-      module,
+      name: resolved.funcName,
+      module: resolved.module,
       secrets,
       effect,
     };
@@ -133,19 +133,18 @@ export class DenoRuntime extends Runtime {
   /** Utility for fetching the current request context */
   fetchContext<C extends t.Typedef>(outputShape?: C): t.Func {
     const returnValue = outputShape ? `context` : "JSON.stringify(context)";
-    return this.func(
-      t.struct({}),
-      outputShape ?? t.json(),
-      { code: `(_, { context }) => ${returnValue}` },
-    );
+    return this.func(t.struct({}), outputShape ?? t.json(), {
+      code: `(_, { context }) => ${returnValue}`,
+    });
   }
 
   policy(name: string, _code: string): Policy;
   policy(name: string, data: Omit<DenoFunc, "effect">): Policy;
   policy(name: string, data: string | Omit<DenoFunc, "effect">): Policy {
-    const params = typeof data === "string"
-      ? { code: data, secrets: [] }
-      : { secrets: [], ...data };
+    const params =
+      typeof data === "string"
+        ? { code: data, secrets: [] }
+        : { secrets: [], ...data };
 
     return Policy.create(
       name,
@@ -156,17 +155,23 @@ export class DenoRuntime extends Runtime {
     );
   }
 
-  importPolicy(data: Omit<DenoImport, "effect">, name?: string): Policy {
-    const policyName = name ??
-      `__imp_${data.module}_${data.name}`.replace(/[^a-zA-Z0-9_]/g, "_");
+  importPolicy(
+    { secrets = [], ...params }: ModuleImportPolicy,
+    name?: string,
+  ): Policy {
+    const resolved = resolveModuleParams(params);
+    const policyName =
+      name ??
+      `__imp_${resolved.module}_${resolved.funcName}`.replace(
+        /[^a-zA-Z0-9_]/g,
+        "_",
+      );
     return Policy.create(
       policyName,
       runtimes.importDenoFunction(
         {
-          funcName: data.name,
-          module: data.module,
-          secrets: data.secrets ?? [],
-          deps: data.deps ?? [],
+          ...resolved,
+          secrets,
         },
         fx.read(),
       ),