codama-renderers-dart 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ifiok Jr.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "codama-renderers-dart",
+  "version": "0.2.0",
+  "description": "Codama renderer for generating Dart code targeting the solana_kit SDK",
+  "exports": {
+    "node": {
+      "import": "./dist/index.node.mjs",
+      "require": "./dist/index.node.cjs"
+    },
+    "browser": {
+      "import": "./dist/index.browser.mjs",
+      "require": "./dist/index.browser.cjs"
+    },
+    "react-native": "./dist/index.react-native.mjs",
+    "types": "./dist/types/index.d.ts"
+  },
+  "main": "./dist/index.node.cjs",
+  "module": "./dist/index.node.mjs",
+  "types": "./dist/types/index.d.ts",
+  "type": "module",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "codama",
+    "solana",
+    "dart",
+    "renderer",
+    "code-generator"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@codama/errors": "^1.4.4",
+    "@codama/nodes": "^1.4.4",
+    "@codama/renderers-core": "^1.3.3",
+    "@codama/visitors-core": "^1.4.4"
+  },
+  "devDependencies": {
+    "@codama/nodes-from-anchor": "^1.3.9",
+    "@codama/renderers-js": "^2.0.2",
+    "@types/node": "^25.3.0",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.3",
+    "vitest": "^3.2.1"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rimraf dist && tsup && tsc -p tsconfig.declarations.json",
+    "lint": "eslint --ext .ts src",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/readme.md

@@ -0,0 +1,297 @@
+# codama-renderers-dart
+
+A [Codama](https://github.com/codama-idl/codama) renderer that generates Dart code targeting the [solana_kit](https://github.com/openbudgetfun/solana_kit) SDK.
+
+Given a Codama IDL (Interface Description Language) describing a Solana program, this renderer produces a complete Dart package with typed account classes, instruction builders, codec functions, error definitions, PDA helpers, and barrel exports.
+
+## Installation
+
+```bash
+pnpm add codama-renderers-dart
+# or
+npm install codama-renderers-dart
+```
+
+## Quick Start
+
+### Programmatic API
+
+```typescript
+import { renderVisitor } from "codama-renderers-dart";
+import { visit } from "@codama/visitors-core";
+import { rootNode, programNode /* ... */ } from "@codama/nodes";
+
+// Build or load a Codama IDL root node
+const root = rootNode(programNode({ /* ... */ }));
+
+// Generate Dart files into the output directory
+visit(root, renderVisitor("lib/src/generated", {
+  formatCode: true,             // Run `dart format` on output (default: false)
+  deleteFolderBeforeRendering: true, // Clean output dir first (default: true)
+}));
+```
+
+### Codama CLI
+
+Create a `codama.json` configuration file:
+
+```json
+{
+  "idl": "idl.json",
+  "scripts": {
+    "dart": {
+      "from": "codama-renderers-dart",
+      "args": ["lib/src/generated"]
+    }
+  }
+}
+```
+
+Then run:
+
+```bash
+codama run dart
+```
+
+## Generated Output Structure
+
+For a program called `myProgram`, the renderer generates:
+
+```
+lib/src/generated/
+  my_program.dart                    # Root barrel export
+  accounts/
+    accounts.dart                    # Category barrel
+    my_account.dart                  # Account type + codecs + decode helper
+  instructions/
+    instructions.dart                # Category barrel
+    my_instruction.dart              # Instruction data + builder + parser
+  types/
+    types.dart                       # Category barrel
+    my_struct.dart                   # Struct type + codecs
+    my_enum.dart                     # Enum/sealed class + codecs
+  errors/
+    errors.dart                      # Category barrel
+    my_program.dart                  # Error constants + message helpers
+  programs/
+    programs.dart                    # Category barrel
+    my_program.dart                  # Program address + identifier enums
+  pdas/
+    pdas.dart                        # Category barrel
+    my_pda.dart                      # PDA seeds class + finder function
+```
+
+## Generated Code Patterns
+
+### Accounts
+
+Each account generates an `@immutable` Dart class with typed fields, const constructor, proper `==`/`hashCode`/`toString` implementations, and codec functions:
+
+```dart
+@immutable
+class MyAccount {
+  const MyAccount({
+    required this.authority,
+    required this.count,
+  });
+
+  final Address authority;
+  final BigInt count;
+
+  // ... equality, hashCode, toString
+}
+
+Encoder<MyAccount> getMyAccountEncoder() { ... }
+Decoder<MyAccount> getMyAccountDecoder() { ... }
+Codec<MyAccount, MyAccount> getMyAccountCodec() { ... }
+Account<MyAccount> decodeMyAccount(EncodedAccount encodedAccount) { ... }
+```
+
+### Instructions
+
+Each instruction generates a data class, codec functions, a builder function, and a parse function:
+
+```dart
+@immutable
+class TransferInstructionData {
+  const TransferInstructionData({
+    this.discriminator = 3,
+    required this.amount,
+  });
+
+  final int discriminator;
+  final BigInt amount;
+}
+
+Instruction getTransferInstruction({
+  required Address programAddress,
+  required Address source,
+  required Address destination,
+  required BigInt amount,
+}) { ... }
+
+TransferInstructionData parseTransferInstruction(Instruction instruction) { ... }
+```
+
+### Scalar Enums
+
+Scalar enums (all-empty variants) generate a Dart `enum` with index-based encoder/decoder:
+
+```dart
+enum AccountStatus {
+  active,
+  frozen,
+  closed,
+}
+
+Encoder<AccountStatus> getAccountStatusEncoder() { ... }
+Decoder<AccountStatus> getAccountStatusDecoder() { ... }
+```
+
+### Data Enums (Discriminated Unions)
+
+Data enums generate Dart 3 `sealed class` hierarchies:
+
+```dart
+sealed class TokenInstruction {
+  const TokenInstruction();
+}
+
+final class Transfer extends TokenInstruction {
+  const Transfer({required this.amount});
+  final BigInt amount;
+}
+
+final class Approve extends TokenInstruction {
+  const Approve({required this.amount});
+  final BigInt amount;
+}
+```
+
+### Errors
+
+Program errors generate constants, a message map, and helper functions:
+
+```dart
+const int myProgramErrorInvalidAuthority = 0x1770; // 6000
+
+String? getMyProgramErrorMessage(int code) { ... }
+bool isMyProgramError(int code) { ... }
+```
+
+### PDAs
+
+PDAs generate a seeds class and finder function:
+
+```dart
+@immutable
+class MyPdaSeeds {
+  const MyPdaSeeds({required this.authority});
+  final Address authority;
+}
+
+Future<(Address, int)> findMyPdaPda({
+  required MyPdaSeeds seeds,
+  required Address programAddress,
+}) async { ... }
+```
+
+## Type Mapping
+
+| Codama Type                         | Dart Type       | Codec                            |
+| ----------------------------------- | --------------- | -------------------------------- |
+| `numberTypeNode(u8/u16/u32)`        | `int`           | `getU8Encoder()` etc.            |
+| `numberTypeNode(u64/u128/i64/i128)` | `BigInt`        | `getU64Encoder()` etc.           |
+| `numberTypeNode(f32/f64)`           | `double`        | `getF32Encoder()` etc.           |
+| `booleanTypeNode`                   | `bool`          | `getBooleanEncoder()`            |
+| `stringTypeNode`                    | `String`        | `getUtf8Encoder()` etc.          |
+| `publicKeyTypeNode`                 | `Address`       | `getAddressEncoder()`            |
+| `bytesTypeNode`                     | `Uint8List`     | `getBytesEncoder()`              |
+| `arrayTypeNode`                     | `List<T>`       | `getArrayEncoder()`              |
+| `mapTypeNode`                       | `Map<K, V>`     | `getMapEncoder()`                |
+| `setTypeNode`                       | `Set<T>`        | `getSetEncoder()`                |
+| `tupleTypeNode`                     | `(T1, T2, ...)` | `getTupleEncoder()`              |
+| `optionTypeNode`                    | `T?`            | `getNullableEncoder()`           |
+| `structTypeNode`                    | Named class     | `getStructEncoder()`             |
+| `enumTypeNode` (scalar)             | `enum`          | `transformEncoder()`             |
+| `enumTypeNode` (data)               | `sealed class`  | `getDiscriminatedUnionEncoder()` |
+
+## Options
+
+### `RenderOptions`
+
+| Option                        | Type                     | Default | Description                                         |
+| ----------------------------- | ------------------------ | ------- | --------------------------------------------------- |
+| `deleteFolderBeforeRendering` | `boolean`                | `true`  | Delete output directory before generating           |
+| `formatCode`                  | `boolean`                | `false` | Run `dart format` on generated files                |
+| `nameApi`                     | `Partial<DartNameApi>`   | —       | Override naming conventions                         |
+| `dependencyMap`               | `Record<string, string>` | —       | Override logical module to Dart package URI mapping |
+
+### `DartNameApi`
+
+All naming conventions are customizable:
+
+```typescript
+import { renderVisitor, createDartNameApi } from "codama-renderers-dart";
+
+const nameApi = {
+  ...createDartNameApi(),
+  dataType: (name) => `My${pascalCase(name)}`,
+};
+
+visit(root, renderVisitor("output", { nameApi }));
+```
+
+## Target Packages
+
+Generated Dart code depends on these solana_kit packages:
+
+- `solana_kit_addresses` — `Address` type and encoder/decoder
+- `solana_kit_codecs_core` — `Encoder`, `Decoder`, `Codec` base types
+- `solana_kit_codecs_data_structures` — Struct, array, boolean, nullable codecs
+- `solana_kit_codecs_numbers` — Number codecs (u8–u128, i8–i128, f32, f64)
+- `solana_kit_codecs_strings` — String codecs (utf8, base58, base64, base16)
+- `solana_kit_accounts` — `Account`, `EncodedAccount`, `decodeAccount`
+- `solana_kit_instructions` — `Instruction`, `AccountMeta`, `AccountRole`
+- `solana_kit_errors` — `SolanaError` error types
+- `meta` — `@immutable` annotation
+
+## Architecture
+
+This renderer follows the same architecture as the official Codama renderers:
+
+1. **Visitor pattern** — Uses `@codama/visitors-core` to traverse the IDL node tree
+2. **Fragment system** — Composable tagged template literals that track imports
+3. **RenderMap** — Maps file paths to code fragments
+4. **Type manifest** — Maps Codama type nodes to Dart types and codec expressions
+
+Key source files:
+
+- `src/visitors/renderVisitor.ts` — Top-level entry point (file I/O)
+- `src/visitors/getRenderMapVisitor.ts` — Maps IDL nodes to output files
+- `src/visitors/getTypeManifestVisitor.ts` — Maps type nodes to Dart types/codecs
+- `src/fragments/*.ts` — Code generation for each entity type
+- `src/utils/` — Import maps, naming, fragment helpers
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Type check
+npx tsc --noEmit
+
+# Run tests
+pnpm test
+
+# Watch mode
+pnpm test:watch
+
+# Build
+pnpm build
+```
+
+## License
+
+MIT

package/src/fragments/accountPage.ts

@@ -0,0 +1,201 @@
+import type { AccountNode, StructFieldTypeNode } from "@codama/nodes";
+import { resolveNestedTypeNode } from "@codama/nodes";
+import { visit } from "@codama/visitors-core";
+
+import type { Fragment } from "../utils/fragment.js";
+import {
+  emptyFragment,
+  fragment,
+  fragmentFromString,
+  mergeFragments,
+  use,
+} from "../utils/fragment.js";
+import type { RenderScope } from "../utils/options.js";
+import { camelCase } from "../utils/nameTransformers.js";
+import { getDiscriminatorConstantsFragment } from "./discriminatorConstants.js";
+
+/**
+ * Generate a full Dart file for an account.
+ */
+export function getAccountPageFragment(
+  node: AccountNode,
+  scope: RenderScope,
+): Fragment {
+  const name = node.name as string;
+  const typeName = scope.nameApi.dataType(name);
+  const dataNode = resolveNestedTypeNode(node.data);
+
+  // Fields from the struct data
+  const fields = dataNode.fields;
+
+  // Visit each field type once and collect manifests for reuse
+  const fieldManifests = fields.map((f: StructFieldTypeNode) => ({
+    field: f,
+    manifest: visit(f.type, scope.typeManifestVisitor),
+  }));
+
+  const fieldDecls = fieldManifests
+    .map(({ field: f, manifest }) => {
+      return `  final ${manifest.type.content} ${camelCase(f.name as string)};`;
+    })
+    .join("\n");
+
+  const ctorParams = fields
+    .map((f: StructFieldTypeNode) => `    required this.${camelCase(f.name as string)},`)
+    .join("\n");
+
+  const eqChecks =
+    fields.length === 0
+      ? "true"
+      : fields
+          .map(
+            (f: StructFieldTypeNode) =>
+              `${camelCase(f.name as string)} == other.${camelCase(f.name as string)}`,
+          )
+          .join(" &&\n          ");
+
+  const hashFields = fields
+    .map((f: StructFieldTypeNode) => camelCase(f.name as string))
+    .join(", ");
+
+  const toStringFields = fields
+    .map(
+      (f: StructFieldTypeNode) =>
+        `${camelCase(f.name as string)}: \$${camelCase(f.name as string)}`,
+    )
+    .join(", ");
+
+  // Encoder fields
+  const encFields = fieldManifests
+    .map(({ field: f, manifest }) => {
+      return `    ('${f.name as string}', ${manifest.encoder.content}),`;
+    })
+    .join("\n");
+
+  const decFields = fieldManifests
+    .map(({ field: f, manifest }) => {
+      return `    ('${f.name as string}', ${manifest.decoder.content}),`;
+    })
+    .join("\n");
+
+  const toMapFields = fields
+    .map(
+      (f: StructFieldTypeNode) =>
+        `      '${f.name as string}': value.${camelCase(f.name as string)},`,
+    )
+    .join("\n");
+
+  const fromMapFields = fieldManifests
+    .map(({ field: f, manifest }) => {
+      const typeStr = manifest.type.content;
+      const isNullable = typeStr.endsWith("?");
+      const accessor = isNullable ? `map['${f.name as string}']` : `map['${f.name as string}']!`;
+      return `      ${camelCase(f.name as string)}: ${accessor} as ${typeStr},`;
+    })
+    .join("\n");
+
+  const encoderName = scope.nameApi.encoderFunction(name);
+  const decoderName = scope.nameApi.decoderFunction(name);
+  const codecName = scope.nameApi.codecFunction(name);
+  const decodeFnName = scope.nameApi.accountDecodeFunction(name);
+
+  // Size
+  const sizeFragment = node.size != null
+    ? fragment`
+/// The size of the [${fragmentFromString(typeName)}] account data in bytes.
+const int ${fragmentFromString(scope.nameApi.accountSizeConstant(name))} = ${fragmentFromString(String(node.size))};`
+    : emptyFragment();
+
+  // Discriminator
+  const discFragment = getDiscriminatorConstantsFragment(node, scope);
+
+  const parts: Fragment[] = [
+    fragment`// Auto-generated. Do not edit.
+// ignore_for_file: type=lint
+
+${use("Uint8List", "dartTypedData")}
+${use("immutable", "meta")}
+${use("Encoder", "solanaCodecsCore")}
+${use("Decoder", "solanaCodecsCore")}
+${use("Codec", "solanaCodecsCore")}
+${use("combineCodec", "solanaCodecsCore")}
+${use("transformEncoder", "solanaCodecsCore")}
+${use("transformDecoder", "solanaCodecsCore")}
+${use("getStructEncoder", "solanaCodecsDataStructures")}
+${use("getStructDecoder", "solanaCodecsDataStructures")}
+${use("Account", "solanaAccounts")}
+${use("EncodedAccount", "solanaAccounts")}
+${use("decodeAccount", "solanaAccounts")}
+
+@immutable
+class ${fragmentFromString(typeName)} {
+  const ${fragmentFromString(typeName)}({
+${fragmentFromString(ctorParams)}
+  });
+
+${fragmentFromString(fieldDecls)}
+
+  @override
+  bool operator ==(Object other) =>
+      identical(this, other) ||
+      other is ${fragmentFromString(typeName)} &&
+          runtimeType == other.runtimeType &&
+          ${fragmentFromString(eqChecks)};
+
+  @override
+  int get hashCode => Object.hash(${fragmentFromString(hashFields)});
+
+  @override
+  String toString() => '${fragmentFromString(typeName)}(${fragmentFromString(toStringFields)})';
+}`,
+  ];
+
+  if (sizeFragment.content) parts.push(sizeFragment);
+  if (discFragment.content) parts.push(discFragment);
+
+  parts.push(fragment`
+Encoder<${fragmentFromString(typeName)}> ${fragmentFromString(encoderName)}() {
+  final structEncoder = getStructEncoder(<(String, Encoder<Object?>)>[
+${fragmentFromString(encFields)}
+  ]);
+
+  return transformEncoder(
+    structEncoder,
+    (${fragmentFromString(typeName)} value) => <String, Object?>{
+${fragmentFromString(toMapFields)}
+    },
+  );
+}
+
+Decoder<${fragmentFromString(typeName)}> ${fragmentFromString(decoderName)}() {
+  final structDecoder = getStructDecoder(<(String, Decoder<Object?>)>[
+${fragmentFromString(decFields)}
+  ]);
+
+  return transformDecoder(
+    structDecoder,
+    (Map<String, Object?> map, Uint8List bytes, int offset) => ${fragmentFromString(typeName)}(
+${fragmentFromString(fromMapFields)}
+    ),
+  );
+}
+
+Codec<${fragmentFromString(typeName)}, ${fragmentFromString(typeName)}> ${fragmentFromString(codecName)}() {
+  return combineCodec(${fragmentFromString(encoderName)}(), ${fragmentFromString(decoderName)}());
+}
+
+Account<${fragmentFromString(typeName)}> ${fragmentFromString(decodeFnName)}(EncodedAccount encodedAccount) {
+  return decodeAccount(encodedAccount, ${fragmentFromString(decoderName)}());
+}`);
+
+  const result = mergeFragments(parts, (cs) => cs.join("\n\n"));
+
+  // Merge field type manifest imports (encoder, decoder, type) into the result
+  for (const { manifest } of fieldManifests) {
+    result.imports.mergeWith(manifest.encoder.imports);
+    result.imports.mergeWith(manifest.decoder.imports);
+    result.imports.mergeWith(manifest.type.imports);
+  }
+
+  return result;
+}

package/src/fragments/discriminatorConstants.ts

@@ -0,0 +1,74 @@
+import type {
+  AccountNode,
+  ConstantDiscriminatorNode,
+  FieldDiscriminatorNode,
+  InstructionNode,
+  SizeDiscriminatorNode,
+} from "@codama/nodes";
+import { visit } from "@codama/visitors-core";
+
+import type { Fragment } from "../utils/fragment.js";
+import { emptyFragment, fragment, fragmentFromString, mergeFragments, use } from "../utils/fragment.js";
+import type { RenderScope } from "../utils/options.js";
+import { bytesToDartHexList } from "../utils/codecs.js";
+
+/**
+ * Generate discriminator constant declarations for an account or instruction.
+ */
+export function getDiscriminatorConstantsFragment(
+  node: AccountNode | InstructionNode,
+  scope: RenderScope,
+): Fragment {
+  const discriminators = node.discriminators ?? [];
+  if (discriminators.length === 0) return emptyFragment();
+
+  const name = node.name as string;
+  const constName = scope.nameApi.discriminatorConstant(name);
+
+  const fragments: Fragment[] = [];
+
+  for (const disc of discriminators) {
+    switch (disc.kind) {
+      case "constantDiscriminatorNode": {
+        const constDisc = disc as ConstantDiscriminatorNode;
+        if (constDisc.constant.value.kind === "bytesValueNode") {
+          const bytes = hexToBytes(constDisc.constant.value.data);
+          const hexList = bytesToDartHexList(bytes);
+          fragments.push(
+            fragment`/// The discriminator bytes for this ${node.kind === "accountNode" ? "account" : "instruction"}.
+final ${constName} = ${use("Uint8List", "dartTypedData")}.fromList(${fragmentFromString(hexList)});`,
+          );
+        }
+        break;
+      }
+      case "fieldDiscriminatorNode": {
+        const fieldDisc = disc as FieldDiscriminatorNode;
+        fragments.push(
+          fragment`/// The discriminator field name: '${fragmentFromString(fieldDisc.name as string)}'.
+/// Offset: ${fragmentFromString(String(fieldDisc.offset))}.`,
+        );
+        break;
+      }
+      case "sizeDiscriminatorNode": {
+        const sizeDisc = disc as SizeDiscriminatorNode;
+        fragments.push(
+          fragment`/// This ${node.kind === "accountNode" ? "account" : "instruction"} has a size discriminator of ${fragmentFromString(String(sizeDisc.size))} bytes.`,
+        );
+        break;
+      }
+    }
+  }
+
+  if (fragments.length === 0) return emptyFragment();
+
+  return mergeFragments(fragments, (cs) => cs.join("\n\n"));
+}
+
+function hexToBytes(hex: string): Uint8Array {
+  const clean = hex.replace(/^0x/, "");
+  const bytes = new Uint8Array(clean.length / 2);
+  for (let i = 0; i < clean.length; i += 2) {
+    bytes[i / 2] = parseInt(clean.slice(i, i + 2), 16);
+  }
+  return bytes;
+}