refactor: improve JSR score (part 1) (#807)

<!--
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 -->

- Add symbol documentations
- Fix slow types

<!-- 2. Explain WHY the change cannot be made simpler -->

-

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

#### Migration notes

...

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

typegate/tests/runtimes/s3/s3_test.ts

@@ -172,7 +172,7 @@ Meta.test("s3", async (t) => {
       }
     `
       .withVars({
-        path: "/",
+        path: "",
       })
       .expectData({
         listObjects: {

typegraph/deno/sdk/jsr.json

@@ -12,11 +12,9 @@
     "./deps/_import.ts": "./src/deps/_import.ts",
     "./deps/mod.ts": "./src/deps/mod.ts",
     "./effects.ts": "./src/effects.ts",
-    "./envs/cli.ts": "./src/envs/cli.ts",
     "./gen/typegraph_core.d.ts": "./src/gen/typegraph_core.d.ts",
     "./host/host.d.ts": "./src/host/host.d.ts",
     "./index.ts": "./src/index.ts",
-    "./io.ts": "./src/io.ts",
     "./metagen.ts": "./src/metagen.ts",
     "./params.ts": "./src/params.ts",
     "./policy.ts": "./src/policy.ts",
@@ -35,8 +33,6 @@
     "./tg_manage.ts": "./src/tg_manage.ts",
     "./typegraph.ts": "./src/typegraph.ts",
     "./types.ts": "./src/types.ts",
-    "./utils/func_utils.ts": "./src/utils/func_utils.ts",
-    "./utils/injection_utils.ts": "./src/utils/injection_utils.ts",
     "./utils/type_utils.ts": "./src/utils/type_utils.ts",
     "./wit.ts": "./src/wit.ts"
   }

typegraph/deno/sdk/src/deps/mod.ts

@@ -13,15 +13,17 @@ export function mapValues(
   return Object.fromEntries(newEntries);
 }
 
-export function dirname(path: string) {
+/** get the directory name from a path */
+export function dirname(path: string): string {
   // Note: Do not refactor with runtime dependent OS check
   const [unixIdx, winIdx] = ["/", "\\"].map((sep) => path.lastIndexOf(sep));
   return path.substring((winIdx > 0 ? winIdx : unixIdx) + 1);
 }
 
 import { fromFileUrlPosix, fromFileUrlWin32 } from "./_import.ts";
 
-export function fromFileUrl(path: string) {
+/** get path from file url */
+export function fromFileUrl(path: string): string {
   // Note: Do not refactor with runtime dependent OS check
   // Examples: file://C:, file://D:
   const isWin32 = /^file:\/\/\w:/.test(path);

typegraph/deno/sdk/src/envs/cli.ts

@@ -95,11 +95,13 @@ export function loadCliEnv(): CliEnv | null {
 
 export const CLI_ENV = loadCliEnv();
 
-export function hasCliEnv() {
+/** check if running in the meta cli */
+export function hasCliEnv(): boolean {
   return CLI_ENV != null;
 }
 
-export function getCliEnv() {
+/** get the envs from meta cli */
+export function getCliEnv(): CliEnv {
   if (CLI_ENV == null) {
     throw new Error("cannot be called in this context");
   }

typegraph/deno/sdk/src/metagen.ts

@@ -39,14 +39,20 @@ export class Metagen {
     } as MdkConfig;
   }
 
-  dryRun(tgOutput: TypegraphOutput, targetName: string, overwrite?: false) {
+  /** dry-run metagen */
+  dryRun(
+    tgOutput: TypegraphOutput,
+    targetName: string,
+    overwrite?: false,
+  ): Array<MdkOutput> {
     const mdkConfig = this.getMdkConfig(tgOutput, targetName);
     return wit_utils.metagenExec(mdkConfig).map((value: any) => ({
       ...value,
       overwrite: overwrite ?? value.overwrite,
     })) as Array<MdkOutput>;
   }
 
+  /** run metagen */
   run(tgOutput: TypegraphOutput, targetName: string, overwrite?: false) {
     const items = this.dryRun(tgOutput, targetName, overwrite);
     wit_utils.metagenWriteFiles(items, this.workspacePath);

typegraph/deno/sdk/src/policy.ts

@@ -58,7 +58,8 @@ export default class Policy {
     );
   }
 
-  static on(effects: PolicyPerEffectAlt) {
+  /** create policy based on effects */
+  static on(effects: PolicyPerEffectAlt): PolicyPerEffectObject {
     return new PolicyPerEffectObject(effects);
   }
 }

typegraph/deno/sdk/src/providers/aws.ts

@@ -33,7 +33,8 @@ export class S3Runtime extends Runtime {
     this.pathStyleSecret = options.pathStyleSecret;
   }
 
-  public presignGet(params: S3PresignGetParams) {
+  /** create a function to presign an S3 GetObject request */
+  public presignGet(params: S3PresignGetParams): t.Func {
     const { bucket, expirySecs } = params;
     const mat: S3PresignGetMat = {
       _id: aws.s3PresignGet(this._id, params),
@@ -43,7 +44,8 @@ export class S3Runtime extends Runtime {
     return t.func(t.struct({ path: t.string() }), t.uri(), mat);
   }
 
-  public presignPut(params: S3PresignPutParams) {
+  /** create a function to presign an S3 PutObject request */
+  public presignPut(params: S3PresignPutParams): t.Func {
     const { bucket, expirySecs, contentType } = params;
     const mat: S3PresignPutMat = {
       _id: aws.s3PresignPut(this._id, params),
@@ -58,10 +60,10 @@ export class S3Runtime extends Runtime {
     );
   }
 
-  /*
-   * list objects
+  /**
+   * create a function to list objects in a bucket
    */
-  public list(bucket: string) {
+  public list(bucket: string): t.Func {
     const mat: S3ListMat = {
       _id: aws.s3List(this._id, bucket),
       bucket,
@@ -76,7 +78,8 @@ export class S3Runtime extends Runtime {
     );
   }
 
-  public upload(bucket: string, overrideFileType?: t.Typedef) {
+  /** create a function for a file upload */
+  public upload(bucket: string, overrideFileType?: t.Typedef): t.Func {
     const fileType = overrideFileType ?? t.file();
     const mat: S3UploadMat = {
       _id: aws.s3Upload(this._id, bucket),
@@ -89,7 +92,8 @@ export class S3Runtime extends Runtime {
     );
   }
 
-  public uploadAll(bucket: string, overrideFileType?: t.Typedef) {
+  /** create a function for multiple file uploads */
+  public uploadAll(bucket: string, overrideFileType?: t.Typedef): t.Func {
     const fileType = overrideFileType ?? t.file();
     const mat: S3UploadAllMat = {
       _id: aws.s3UploadAll(this._id, bucket),

typegraph/deno/sdk/src/providers/prisma.ts

@@ -27,111 +27,125 @@ export class PrismaRuntime extends Runtime {
     this.connectionStringSecret = connectionStringSecret;
   }
 
-  findUnique(model: string | Typedef) {
+  /** create a function for a prisma `findUnique` query */
+  findUnique(model: string | Typedef): t.Func {
     if (typeof model == "string") {
       model = genRef(model);
     }
     const type = runtimes.prismaFindUnique(this._id, model._id);
     return t.Func.fromTypeFunc(type);
   }
 
-  findMany(model: string | Typedef) {
+  /** create a function for a prisma `findMany` query */
+  findMany(model: string | Typedef): t.Func {
     if (typeof model == "string") {
       model = genRef(model);
     }
     const type = runtimes.prismaFindMany(this._id, model._id);
     return t.Func.fromTypeFunc(type);
   }
 
-  findFirst(model: string | Typedef) {
+  /** create a function for a prisma `findFirst` query */
+  findFirst(model: string | Typedef): t.Func {
     if (typeof model == "string") {
       model = genRef(model);
     }
     const type = runtimes.prismaFindFirst(this._id, model._id);
     return t.Func.fromTypeFunc(type);
   }
 
-  aggregate(model: string | Typedef) {
+  /** create a function for a prisma `aggregate` query */
+  aggregate(model: string | Typedef): t.Func {
     if (typeof model == "string") {
       model = genRef(model);
     }
     const type = runtimes.prismaAggregate(this._id, model._id);
     return t.Func.fromTypeFunc(type);
   }
 
-  count(model: string | Typedef) {
+  /** create a function for a prisma `count` query */
+  count(model: string | Typedef): t.Func {
     if (typeof model == "string") {
       model = genRef(model);
     }
     const type = runtimes.prismaCount(this._id, model._id);
     return t.Func.fromTypeFunc(type);
   }
 
-  groupBy(model: string | Typedef) {
+  /** create a function for a prisma `groupBy` query */
+  groupBy(model: string | Typedef): t.Func {
     if (typeof model == "string") {
       model = genRef(model);
     }
     const type = runtimes.prismaGroupBy(this._id, model._id);
     return t.Func.fromTypeFunc(type);
   }
 
-  create(model: string | Typedef) {
+  /** create a function for a prisma `create` query */
+  create(model: string | Typedef): t.Func {
     if (typeof model == "string") {
       model = genRef(model);
     }
     const type = runtimes.prismaCreateOne(this._id, model._id);
     return t.Func.fromTypeFunc(type);
   }
 
-  createMany(model: string | Typedef) {
+  /** create a function for a prisma `createMany` query */
+  createMany(model: string | Typedef): t.Func {
     if (typeof model == "string") {
       model = genRef(model);
     }
     const type = runtimes.prismaCreateMany(this._id, model._id);
     return t.Func.fromTypeFunc(type);
   }
 
-  update(model: string | Typedef) {
+  /** create a function for a prisma `update` query */
+  update(model: string | Typedef): t.Func {
     if (typeof model == "string") {
       model = genRef(model);
     }
     const type = runtimes.prismaUpdateOne(this._id, model._id);
     return t.Func.fromTypeFunc(type);
   }
 
-  updateMany(model: string | Typedef) {
+  /** create a function for a prisma `updateMany` query */
+  updateMany(model: string | Typedef): t.Func {
     if (typeof model == "string") {
       model = genRef(model);
     }
     const type = runtimes.prismaUpdateMany(this._id, model._id);
     return t.Func.fromTypeFunc(type);
   }
 
-  upsert(model: string | Typedef) {
+  /** create a function for a prisma `upsert` query */
+  upsert(model: string | Typedef): t.Func {
     if (typeof model == "string") {
       model = genRef(model);
     }
     const type = runtimes.prismaUpsertOne(this._id, model._id);
     return t.Func.fromTypeFunc(type);
   }
 
-  delete(model: string | Typedef) {
+  /** create a function for a prisma `delete` query */
+  delete(model: string | Typedef): t.Func {
     if (typeof model == "string") {
       model = genRef(model);
     }
     const type = runtimes.prismaDeleteOne(this._id, model._id);
     return t.Func.fromTypeFunc(type);
   }
 
-  deleteMany(model: string | Typedef) {
+  /** create a function for a prisma `deleteMany` query */
+  deleteMany(model: string | Typedef): t.Func {
     if (typeof model == "string") {
       model = genRef(model);
     }
     const type = runtimes.prismaDeleteMany(this._id, model._id);
     return t.Func.fromTypeFunc(type);
   }
 
-  execute(query: string, parameters: Typedef, effect: Effect) {
+  /** create a function for prisma `execute` */
+  execute(query: string, parameters: Typedef, effect: Effect): t.Func {
     const type = runtimes.prismaExecute(
       this._id,
       query,
@@ -141,7 +155,8 @@ export class PrismaRuntime extends Runtime {
     return t.Func.fromTypeFunc(type);
   }
 
-  queryRaw(query: string, parameters: Typedef | null, output: Typedef) {
+  /** create a function for prisma `queryRaw` */
+  queryRaw(query: string, parameters: Typedef | null, output: Typedef): t.Func {
     const type = runtimes.prismaQueryRaw(
       this._id,
       query,
@@ -151,7 +166,12 @@ export class PrismaRuntime extends Runtime {
     return t.Func.fromTypeFunc(type);
   }
 
-  link(targetType: string | Typedef, name: string, arg?: PrismaLinkArg) {
+  /** define a relationship */
+  link(
+    targetType: string | Typedef,
+    name: string,
+    arg?: PrismaLinkArg,
+  ): Typedef {
     return prismaLink(targetType, name, arg ?? {});
   }
 }
@@ -160,7 +180,7 @@ function prismaLink(
   targetType: string | Typedef,
   name?: string,
   arg?: PrismaLinkArg,
-) {
+): Typedef {
   if (typeof targetType == "string") {
     targetType = genRef(targetType);
   }

typegraph/deno/sdk/src/providers/temporal.ts

@@ -50,7 +50,8 @@ export class TemporalRuntime extends Runtime {
     return Func.fromTypeFunc(dataFunc);
   }
 
-  startWorkflow(workflowType: string, arg: Typedef) {
+  /** create a function to start a workflow */
+  startWorkflow(workflowType: string, arg: Typedef): Func {
     return this.#genericTemporalFunc(
       {
         tag: "start-workflow",
@@ -60,7 +61,8 @@ export class TemporalRuntime extends Runtime {
     );
   }
 
-  signalWorkflow(signalName: string, arg: Typedef) {
+  /** create a function to signal a workflow */
+  signalWorkflow(signalName: string, arg: Typedef): Func {
     return this.#genericTemporalFunc(
       {
         tag: "signal-workflow",
@@ -70,7 +72,8 @@ export class TemporalRuntime extends Runtime {
     );
   }
 
-  queryWorkflow(queryType: string, arg: Typedef, out: Typedef) {
+  /** create a function to query a workflow */
+  queryWorkflow(queryType: string, arg: Typedef, out: Typedef): Func {
     return this.#genericTemporalFunc(
       {
         tag: "query-workflow",
@@ -81,7 +84,8 @@ export class TemporalRuntime extends Runtime {
     );
   }
 
-  describeWorkflow() {
+  /** create a function that describes a workflow */
+  describeWorkflow(): Func {
     return this.#genericTemporalFunc({ tag: "describe-workflow" });
   }
 }

typegraph/deno/sdk/src/runtimes/deno.ts

@@ -115,7 +115,8 @@ export class DenoRuntime extends Runtime {
     return t.func(inp, inp, mat);
   }
 
-  static<P extends t.Typedef>(out: P, value: any) {
+  /** use a static function already registered on the typegate */
+  static<P extends t.Typedef>(out: P, value: any): t.Func {
     const mat = {
       _id: runtimes.registerDenoStatic(
         {