skir-typescript-gen 0.0.1

package/README.md

@@ -0,0 +1,370 @@
+[![npm](https://img.shields.io/npm/v/skir-typescript-gen)](https://www.npmjs.com/package/skir-typescript-gen)
+[![build](https://github.com/gepheum/skir-typescript-gen/workflows/Build/badge.svg)](https://github.com/gepheum/skir-typescript-gen/actions)
+
+# Skir's TypeScript code generator
+
+Official plugin for generating TypeScript/JavaScript code from [.skir](https://github.com/gepheum/skir) files.
+
+Generated code can run Node, Deno or in the browser.
+
+## Installation
+
+From your project's root directory, run `npm i --save-dev skir-typescript-gen`.
+
+In your `skir.yml` file, add the following snippet under `generators`:
+```yaml
+  - mod: skir-typescript-gen
+    config:
+      # Possible values: "" (CommonJS), ".js" (ES Modules), ".ts" (Deno)
+      importPathExtension: ""
+```
+
+The `npm run skirc` command will now generate .js and .t.ts files within the `skirout` directory.
+
+For more information, see this TypeScript project [example](https://github.com/gepheum/skir-typescript-example).
+
+## TypeScript generated code guide
+
+The examples below are for the code generated from [this](https://github.com/gepheum/skir-typescript-example/blob/main/skir_src/user.skir) .skir file.
+
+### Referring to generated symbols
+
+```typescript
+import { TARZAN, User, UserHistory, UserRegistry } from "../skirout/user";
+```
+
+### Struct classes
+
+For every struct `S` in the .skir file, skir generates a frozen (deeply immutable) class `S` and a mutable class `S.Mutable`.
+
+#### Frozen struct classes
+
+```typescript
+// Construct a frozen User with User.create({...})
+const john = User.create({
+  userId: 42,
+  name: "John Doe",
+  quote: "Coffee is just a socially acceptable form of rage.",
+  pets: [
+    {
+      name: "Dumbo",
+      heightInMeters: 1.0,
+      picture: "🐘",
+    },
+  ],
+  subscriptionStatus: "FREE",
+  // foo: "bar",
+  // ^ Does not compile: 'foo' is not a field of User
+});
+
+assert(john.name === "John Doe");
+
+// john.name = "John Smith";
+// ^ Does not compile: all the properties are read-only
+
+// With create<"partial">({...}), you don't need to specify all the fields of
+// the struct.
+const jane = User.create<"partial">({
+  userId: 43,
+  name: "Jane Doe",
+  pets: [{ name: "Fluffy" }, { name: "Fido" }],
+});
+
+// Missing fields are initialized to their default values.
+assert(jane.quote === "");
+
+const janeHistory = UserHistory.create({
+  user: jane,
+  // ^ the object you pass to create({...}) can contain struct values
+  sessions: [
+    {
+      login: Timestamp.fromUnixMillis(1234),
+      logout: Timestamp.fromUnixMillis(2345),
+    },
+  ],
+});
+
+const defaultUser = User.DEFAULT;
+assert(defaultUser.name === "");
+// User.DEFAULT is same as User.create<"partial">({});
+```
+
+#### Mutable struct classes
+
+```typescript
+// User.Mutable is a mutable version of User.
+const lylaMut = new User.Mutable();
+lylaMut.userId = 44;
+lylaMut.name = "Lyla Doe";
+
+// The User.Mutable() constructor also accepts an initializer object.
+const jolyMut = new User.Mutable({ userId: 45 });
+jolyMut.name = "Joly Doe";
+
+// jolyHistoryMut.user.quote = "I am Joly.";
+// ^ Does not compile: quote is readonly because jolyHistoryMut.user might be
+// a frozen struct
+
+const jolyHistoryMut = new UserHistory.Mutable();
+jolyHistoryMut.user = jolyMut;
+// ^ The right-hand side of the assignment can be either frozen or mutable.
+
+// The mutableUser() getter first checks if 'user' is already a mutable struct,
+// and if so, returns it. Otherwise, it assigns to 'user' a mutable shallow copy
+// of itself and returns it.
+jolyHistoryMut.mutableUser.quote = "I am Joly.";
+
+// Similarly, mutablePets() first checks if 'pets' is already a mutable array,
+// and if so, returns it. Otherwise, it assigns to 'pets' a mutable shallow copy
+// of itself and returns it.
+lylaMut.mutablePets.push(User.Pet.create<"partial">({ name: "Cupcake" }));
+lylaMut.mutablePets.push(new User.Pet.Mutable({ name: "Simba" }));
+```
+
+#### Converting between frozen and mutable
+
+```typescript
+// toMutable() does a shallow copy of the frozen struct, so it's cheap. All the
+// properties of the copy hold a frozen value.
+const evilJaneMut = jane.toMutable();
+evilJaneMut.name = "Evil Jane";
+
+// toFrozen() recursively copies the mutable values held by properties of the
+// object. It's cheap if all the values are frozen, like in this example.
+const evilJane: User = evilJaneMut.toFrozen();
+```
+
+#### Writing logic agnostic of mutability
+
+```typescript
+// 'User.OrMutable' is a type alias for 'User | User.Mutable'.
+function greet(user: User.OrMutable) {
+  console.log(`Hello, ${user.name}`);
+}
+
+greet(jane);
+// Hello, Jane Doe
+greet(lylaMut);
+// Hello, Lyla Doe
+```
+
+### Enum classes
+
+The definition of the `SubscriptionStatus` enum in the .skir file is:
+```rust
+enum SubscriptionStatus {
+  FREE;
+  trial: Trial;
+  PREMIUM;
+}
+```
+
+#### Making enum values
+
+```typescript
+const johnStatus = User.SubscriptionStatus.FREE;
+const janeStatus = User.SubscriptionStatus.PREMIUM;
+const lylaStatus = User.SubscriptionStatus.create("PREMIUM");
+// ^ same as User.SubscriptionStatus.PREMIUM
+const jolyStatus = User.SubscriptionStatus.UNKNOWN;
+
+// Use create({kind: ..., value: ...}) for data variants.
+const roniStatus = User.SubscriptionStatus.create({
+  kind: "trial",
+  value: {
+    startTime: Timestamp.fromUnixMillis(1234),
+  },
+});
+```
+
+#### Conditions on enums
+
+```typescript
+// Use e.kind === "CONSTANT_NAME" to check if the enum value is a constant.
+assert(johnStatus.kind === "FREE");
+assert(johnStatus.value === undefined);
+
+// Use "?" for UNKNOWN.
+assert(jolyStatus.kind === "?");
+
+assert(roniStatus.kind === "trial");
+assert(roniStatus.value!.startTime.unixMillis === 1234);
+
+function getSubscriptionInfoText(status: User.SubscriptionStatus): string {
+  // Use the 'union' getter for typesafe switches on enums.
+  switch (status.union.kind) {
+    case "?":
+      return "Unknown subscription status";
+    case "FREE":
+      return "Free user";
+    case "PREMIUM":
+      return "Premium user";
+    case "trial":
+      // Here the compiler knows that the type of union.value is 'User.Trial'.
+      return "On trial since " + status.union.value.startTime;
+  }
+}
+```
+
+### Serialization
+
+Every frozen struct class and enum class has a static readonly `serializer` property which can be used for serializing and deserializing instances of the class.
+
+```typescript
+
+const serializer = User.serializer;
+
+// Serialize 'john' to dense JSON.
+console.log(serializer.toJsonCode(john));
+// [42,"John Doe"]
+
+// Serialize 'john' to readable JSON.
+console.log(serializer.toJsonCode(john, "readable"));
+// {
+//   "user_id": 42,
+//   "name": "John Doe"
+// }
+
+// The dense JSON flavor is the flavor you should pick if you intend to
+// deserialize the value in the future. Skir allows fields to be renamed, and
+// because fields names are not part of the dense JSON, renaming a field does
+// not prevent you from deserializing the value.
+// You should pick the readable flavor mostly for debugging purposes.
+
+// Serialize 'john' to binary format.
+console.log(serializer.toBytes(john));
+
+// The binary format is not human readable, but it is slightly more compact than
+// JSON, and serialization/deserialization can be a bit faster in languages like
+// C++. Only use it when this small performance gain is likely to matter, which
+// should be rare.
+```
+
+### Deserialization
+
+```typescript
+// Use fromJson(), fromJsonCode() and fromBytes() to deserialize.
+
+const reserializedJohn = serializer.fromJsonCode(serializer.toJsonCode(john));
+assert(reserializedJohn.name === "John Doe");
+
+const reserializedJane = serializer.fromJsonCode(
+  serializer.toJsonCode(jane, "readable"),
+);
+assert(reserializedJane.name === "Jane Doe");
+
+const reserializedLyla = serializer.fromBytes(
+  serializer.toBytes(lylaMut).toBuffer(),
+);
+assert(reserializedLyla.name === "Lyla Doe");
+```
+
+### Frozen arrays and copies
+
+```typescript
+const pets = [
+  User.Pet.create<"partial">({ name: "Fluffy" }),
+  User.Pet.create<"partial">({ name: "Fido" }),
+];
+
+const jade = User.create<"partial">({
+  pets: pets,
+  // ^ makes a copy of 'pets' because 'pets' is mutable
+});
+
+// jade.pets.push(...)
+// ^ Compile-time error: pets is readonly
+
+assert(jade.pets !== pets);
+
+const jack = User.create<"partial">({
+  pets: jade.pets,
+  // ^ doesn't make a copy because 'jade.pets' is frozen
+});
+
+assert(jack.pets === jade.pets);
+```
+
+### Keyed arrays
+
+```typescript
+const userRegistry = UserRegistry.create({
+  users: [john, jane, lylaMut],
+});
+
+// searchUsers() returns the user with the given key (specified in the .skir
+// file). In this example, the key is the user id.
+// The first lookup runs in O(N) time, and the following lookups run in O(1)
+// time.
+assert(userRegistry.searchUsers(42) === john);
+assert(userRegistry.searchUsers(100) === undefined);
+```
+
+### Constants
+
+```typescript
+console.log(TARZAN);
+// User {
+//   userId: 123,
+//   name: 'Tarzan',
+//   quote: 'AAAAaAaAaAyAAAAaAaAaAyAAAAaAaAaA',
+//   pets: [ User_Pet { name: 'Cheeta', heightInMeters: 1.67, picture: '🐒' } ],
+//   subscriptionStatus: User_SubscriptionStatus {
+//     kind: 'trial',
+//     value: User_Trial { startTime: [Timestamp] }
+//   }
+// }
+```
+
+### Skir services
+
+#### Starting a skir service on an HTTP server
+
+Full example [here](https://github.com/gepheum/skir-typescript-example/blob/main/src/server.ts).
+
+#### Sending RPCs to a skir service
+
+Full example [here](https://github.com/gepheum/skir-typescript-example/blob/main/src/client.ts).
+
+### Reflection
+
+Reflection allows you to inspect a skir type at runtime.
+
+```typescript
+const fieldNames: string[] = [];
+for (const field of User.serializer.typeDescriptor.fields) {
+  const { name, number, property, type } = field;
+  fieldNames.push(name);
+}
+console.log(fieldNames);
+// [ 'user_id', 'name', 'quote', 'pets', 'subscription_status' ]
+
+// A type descriptor can be serialized to JSON and deserialized later.
+const typeDescriptor = parseTypeDescriptorFromJson(
+  User.serializer.typeDescriptor.asJson(),
+);
+```
+
+### Writing unit tests
+
+With mocha and [buckwheat](https://github.com/gepheum/buckwheat).
+
+```typescript
+expect(tarzan).toMatch({
+  name: "Tarzan",
+  quote: /^A/, // must start with the letter A
+  pets: [
+    {
+      name: "Cheeta",
+      heightInMeters: near(1.6, 0.1),
+    },
+  ],
+  subscriptionStatus: {
+    kind: "trial",
+    value: {
+      startTime: Timestamp.fromUnixMillis(1234),
+    },
+  },
+  // `userId` is not specified so it can be anything
+});
+```

package/dist/class_speller.d.ts

@@ -0,0 +1,48 @@
+import type { Module, RecordLocation } from "skir-internal";
+export interface ClassName {
+    /**
+     * Name of the TypeScript class, e.g. "Bar". It is obtained by taking the
+     * record name, as specified in the '.skir' file, and appending one or
+     * multiple underscores if there is a conflict with another name.
+     * If the class is nested, the `name` does not include the name of the parent
+     * classes.
+     */
+    readonly name: string;
+    /**
+     * Qualified type name, e.g. "Foo.Bar".
+     * This is what you want to use in type declarations.
+     */
+    readonly type: string;
+    /**
+     * Class expression, e.g. "Foo_Bar" if the class is defined in the same
+     * module, or "x_other_module.Foo.Bar" if it is defined in a different module.
+     * This is what you want to use in the TypeScript code that gets transpiled to
+     * Javascript.
+     */
+    readonly value: string;
+    /**
+     * Expression referring to the parent class if this class is nested, undefined
+     * otherwise.
+     */
+    parentClassValue: string | undefined;
+    /**
+     * Name of the record, as specified in the '.skir' file. This can be different
+     * from `name` if for example the record name conflicts with a built-in class.
+     * If the record is nested, the `recordName` does not include the name of the
+     * parent records.
+     */
+    readonly recordName: string;
+    /**
+     * Dot-separated record names, where the first record is a record defined at
+     * the top-level, the last record is this record, and every record in the
+     * chain is nested within the previous record.
+     */
+    readonly recordQualifiedName: string;
+    readonly recordType: "struct" | "enum";
+    /** True if the class is nested within another class. */
+    readonly isNested: boolean;
+}
+/** Returns the name of the frozen TypeScript class for the given record. */
+export declare function getClassName(record: RecordLocation, origin: Module): ClassName;
+export declare function maybeEscapeTopLevelUpperCaseName(name: string): string;
+//# sourceMappingURL=class_speller.d.ts.map

package/dist/class_speller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"class_speller.d.ts","sourceRoot":"","sources":["../src/class_speller.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE5D,MAAM,WAAW,SAAS;IACxB;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IAErC,QAAQ,CAAC,UAAU,EAAE,QAAQ,GAAG,MAAM,CAAC;IACvC,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,4EAA4E;AAC5E,wBAAgB,YAAY,CAC1B,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,MAAM,GACb,SAAS,CA6DX;AAED,wBAAgB,gCAAgC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErE"}

package/dist/class_speller.js

@@ -0,0 +1,84 @@
+/** Returns the name of the frozen TypeScript class for the given record. */
+export function getClassName(record, origin) {
+    const recordType = record.record.recordType;
+    const { recordAncestors } = record;
+    const isNested = recordAncestors.length >= 2;
+    const seenNames = new Set();
+    const parts = [];
+    for (let i = 0; i < recordAncestors.length; ++i) {
+        const reservedNames = i === 0
+            ? BUILTIN_TYPE_NAMES
+            : recordAncestors[i - 1].recordType === "struct"
+                ? STRUCT_NESTED_TYPE_NAMES
+                : ENUM_NESTED_TYPE_NAMES;
+        const record = recordAncestors[i];
+        let name = record.name.text;
+        while (seenNames.has(name) || reservedNames.has(name)) {
+            name += "_";
+        }
+        parts.push(name);
+        seenNames.add(name);
+    }
+    const name = parts.at(-1);
+    const recordName = record.record.name.text;
+    const recordQualifiedName = recordAncestors.map((r) => r.name.text).join(".");
+    let type;
+    let value;
+    let parentClassValue;
+    if (record.modulePath !== origin.path) {
+        // The record is located in an imported module.
+        const path = record.modulePath;
+        const importedNames = origin.pathToImportedNames[path];
+        if (importedNames.kind === "all") {
+            const alias = importedNames.alias;
+            type = [`x_${alias}`].concat(parts).join(".");
+        }
+        else {
+            type = `${parts.join(".")}`;
+        }
+        value = type;
+    }
+    else {
+        type = parts.join(".");
+        value = parts.join("_");
+        if (isNested) {
+            parentClassValue = parts.slice(0, -1).join("_");
+        }
+    }
+    return {
+        name: name,
+        type: type,
+        value: value,
+        parentClassValue: parentClassValue,
+        recordName: recordName,
+        recordQualifiedName: recordQualifiedName,
+        recordType: recordType,
+        isNested: isNested,
+    };
+}
+export function maybeEscapeTopLevelUpperCaseName(name) {
+    return BUILTIN_TYPE_NAMES.has(name) ? `${name}_` : name;
+}
+const BUILTIN_TYPE_NAMES = new Set([
+    // Subset of the standard built-in Typescript types and Javascript class names
+    // used in the generated code, either in the ".d.ts" file or the ".js" file.
+    // We can't use those as names for generated declarations at the top-level.
+    "Array",
+    "BigInt",
+    "Partial",
+    "ReadonlyArray",
+]);
+/** Generated types nested within a struct namespace. */
+const STRUCT_NESTED_TYPE_NAMES = new Set([
+    "Initializer",
+    "Mutable",
+    "OrMutable",
+]);
+/** Generated types nested within an enum namespace. */
+const ENUM_NESTED_TYPE_NAMES = new Set([
+    "Initializer",
+    "Kind",
+    "Value",
+    "UnionView",
+]);
+//# sourceMappingURL=class_speller.js.map

package/dist/class_speller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"class_speller.js","sourceRoot":"","sources":["../src/class_speller.ts"],"names":[],"mappings":"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"}

package/dist/expression_maker.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview Returns a TypeScript expression transforming a value from a
+ * `initializer` type into a `frozen` type.
+ */
+import type { ResolvedType } from "skir-internal";
+import { TypeSpeller } from "./type_speller.js";
+export interface ToFrozenExpressionArg {
+    type: ResolvedType;
+    inExpr: string;
+    maybeUndefined: boolean;
+    typeSpeller: TypeSpeller;
+}
+export declare function toFrozenExpression(arg: ToFrozenExpressionArg): string;
+//# sourceMappingURL=expression_maker.d.ts.map

package/dist/expression_maker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expression_maker.d.ts","sourceRoot":"","sources":["../src/expression_maker.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,YAAY,CAAC;IAEnB,MAAM,EAAE,MAAM,CAAC;IAEf,cAAc,EAAE,OAAO,CAAC;IACxB,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,qBAAqB,GAAG,MAAM,CA2FrE"}

package/dist/expression_maker.js

@@ -0,0 +1,120 @@
+export function toFrozenExpression(arg) {
+    const { type, inExpr, maybeUndefined, typeSpeller } = arg;
+    if (type.kind === "record") {
+        const frozenClass = typeSpeller.getClassName(type.key);
+        const defaultExpr = type.recordType === "struct"
+            ? `${frozenClass.value}.DEFAULT`
+            : `${frozenClass.value}.UNKNOWN`;
+        const inExprOrDefault = maybeUndefined
+            ? `${inExpr} ?? ${defaultExpr}`
+            : inExpr;
+        return `${frozenClass.value}.create(${inExprOrDefault})`;
+    }
+    else if (type.kind === "array") {
+        const transformItemExpr = toFrozenExpression({
+            type: type.item,
+            inExpr: "e",
+            maybeUndefined: false,
+            typeSpeller: typeSpeller,
+        });
+        const inExprOrEmpty = maybeUndefined ? `${inExpr} || []` : inExpr;
+        if (transformItemExpr === "e") {
+            return `$._toFrozenArray(\n${inExprOrEmpty})`;
+        }
+        else {
+            let mapFnExpr;
+            if (type.item.kind === "record") {
+                // Instead of creating a lambda, we can just get the `create` static
+                // function.
+                const frozenClass = typeSpeller.getClassName(type.item.key);
+                mapFnExpr = `${frozenClass.value}.create`;
+            }
+            else {
+                mapFnExpr = `(e) => ${transformItemExpr}`;
+            }
+            const funName = "$._toFrozenArray";
+            return `${funName}(\n${inExprOrEmpty},\n${mapFnExpr},\n)`;
+        }
+    }
+    else if (type.kind === "optional") {
+        const otherType = type.other;
+        const otherExpr = toFrozenExpression({
+            type: otherType,
+            inExpr: inExpr,
+            maybeUndefined: false,
+            typeSpeller: typeSpeller,
+        });
+        if (otherExpr === inExpr) {
+            return maybeUndefined ? `${inExpr} ?? null` : inExpr;
+        }
+        // The condition for returning otherExpr.
+        let condition;
+        if (canBeFalsy(otherType)) {
+            if (maybeUndefined) {
+                // This is one way to test that inExpr is not null or undefined.
+                // Works because if inExpr was === 0, then we would have already
+                // returned.
+                condition = `((${inExpr} ?? 0) !== 0)`;
+            }
+            else {
+                condition = `${inExpr} !== null`;
+            }
+        }
+        else {
+            // Just rely on implicit boolean conversion.
+            // Also works if maybeUndefined is true.
+            condition = inExpr;
+        }
+        return `${condition} ? ${otherExpr} : null`;
+    }
+    // A primitive type.
+    if (!maybeUndefined) {
+        return inExpr;
+    }
+    const { primitive } = type;
+    let defaultValue;
+    if (primitive === "bool") {
+        defaultValue = "false";
+    }
+    else if (primitive === "int32" ||
+        primitive === "float32" ||
+        primitive === "float64") {
+        defaultValue = "0";
+    }
+    else if (primitive === "int64" || primitive === "uint64") {
+        defaultValue = "BigInt(0)";
+    }
+    else if (primitive === "timestamp") {
+        defaultValue = "$.Timestamp.UNIX_EPOCH";
+    }
+    else if (primitive === "string") {
+        defaultValue = '""';
+    }
+    else if (primitive === "bytes") {
+        defaultValue = "$.ByteString.EMPTY";
+    }
+    else {
+        const _ = primitive;
+        throw TypeError();
+    }
+    return `${inExpr} ?? ${defaultValue}`;
+}
+// Returns true if values of the given type can ever be falsy.
+// See https://developer.mozilla.org/en-US/docs/Glossary/Falsy
+function canBeFalsy(type) {
+    if (type.kind === "optional") {
+        return true;
+    }
+    if (type.kind !== "primitive") {
+        return false;
+    }
+    const { primitive } = type;
+    return (primitive === "bool" ||
+        primitive === "int32" ||
+        primitive === "int64" ||
+        primitive === "uint64" ||
+        primitive === "float32" ||
+        primitive === "float64" ||
+        primitive === "string");
+}
+//# sourceMappingURL=expression_maker.js.map

package/dist/expression_maker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expression_maker.js","sourceRoot":"","sources":["../src/expression_maker.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import type { CodeGenerator } from "skir-internal";
+import { z } from "zod";
+declare const Config: z.ZodObject<{
+    importPathExtension: z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodLiteral<".js">, z.ZodLiteral<".ts">]>;
+    clientModulePath: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type Config = z.infer<typeof Config>;
+declare class TypescriptCodeGenerator implements CodeGenerator<Config> {
+    readonly id = "typescript";
+    readonly configType: z.ZodObject<{
+        importPathExtension: z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodLiteral<".js">, z.ZodLiteral<".ts">]>;
+        clientModulePath: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    readonly version = "1.0.0";
+    generateCode(input: CodeGenerator.Input<Config>): CodeGenerator.Output;
+}
+export declare const GENERATOR: TypescriptCodeGenerator;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EAOd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAYxB,QAAA,MAAM,MAAM;;;iBAOV,CAAC;AAEH,KAAK,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC;AAErC,cAAM,uBAAwB,YAAW,aAAa,CAAC,MAAM,CAAC;IAC5D,QAAQ,CAAC,EAAE,gBAAgB;IAC3B,QAAQ,CAAC,UAAU;;;sBAAU;IAC7B,QAAQ,CAAC,OAAO,WAAW;IAE3B,YAAY,CAAC,KAAK,EAAE,aAAa,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,aAAa,CAAC,MAAM;CAyBvE;AAkvBD,eAAO,MAAM,SAAS,yBAAgC,CAAC"}