codama-renderers-dart 0.5.0 → 0.5.3

package/{readme.md → README.md}

@@ -6,23 +6,21 @@ A [Codama](https://github.com/codama-idl/codama) renderer that generates Dart co
 
 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.
 
+Fixed-size Codama types generate non-truncating encoders. Values within the declared byte capacity are zero-padded, while over-capacity values throw before any malformed bytes can be emitted. For UTF-8 strings, capacity is measured in encoded bytes rather than Dart code units.
+
 ## Installation
 
 ```bash
 pnpm add codama-renderers-dart
 # or
-
-[![pub package](https://img.shields.io/pub/v/codama-renderers-dart.svg)](https://pub.dev/packages/codama-renderers-dart)
-[![CI](https://github.com/openbudgetfun/solana_kit/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/openbudgetfun/solana_kit/actions/workflows/ci.yml)
-[![Coverage](https://codecov.io/gh/openbudgetfun/solana_kit/branch/main/graph/badge.svg?flag=codama-renderers-dart)](https://codecov.io/gh/openbudgetfun/solana_kit?flag=codama-renderers-dart)
 npm install codama-renderers-dart
 ```
 
-## Quick Start
+## Quick start
 
 ### Programmatic API
 
-```typescript
+```ts
 import { renderVisitor } from "codama-renderers-dart";
 import { visit } from "@codama/visitors-core";
 import { rootNode, programNode /* ... */ } from "@codama/nodes";
@@ -37,6 +35,21 @@ visit(root, renderVisitor("lib/src/generated", {
 }));
 ```
 
+### Serialized Pina IDLs
+
+`renderVisitor` accepts parsed Codama JSON as well as roots made with Codama constructors. Pina omits empty collections from its serialized IDLs; the renderer restores those structural defaults on an internal copy before traversal, leaving the parsed object unchanged.
+
+```ts
+import { readFile } from "node:fs/promises";
+import { visit } from "@codama/visitors-core";
+import { renderVisitor } from "codama-renderers-dart";
+
+const idl = JSON.parse(await readFile("target/codama/my_program.json", "utf8"));
+visit(idl, renderVisitor("lib/src/generated"));
+```
+
+Use `normalizeRootNode(idl)` when calling lower-level visitors such as `getRenderMapVisitor` directly.
+
 ### Codama CLI
 
 Create a `codama.json` configuration file:
@@ -59,7 +72,7 @@ Then run:
 codama run dart
 ```
 
-## Generated Output Structure
+## Generated output structure
 
 For a program called `myProgram`, the renderer generates:
 
@@ -87,7 +100,7 @@ lib/src/generated/
     my_pda.dart                      # PDA seeds class + finder function
 ```
 
-## Generated Code Patterns
+## Generated code patterns
 
 ### Accounts
 
@@ -139,7 +152,17 @@ Instruction getTransferInstruction({
 TransferInstructionData parseTransferInstruction(Instruction instruction) { ... }
 ```
 
-### Scalar Enums
+### Discriminators and omitted defaults
+
+Generated codecs treat Codama discriminators as wire invariants rather than caller input. A struct field or instruction argument with a default value strategy of `omitted` is not accepted by the generated constructor or instruction builder. Its declared default is always written by the encoder.
+
+Account and instruction decoders validate every declared constant, field, and size discriminator before returning typed data. Invalid discriminator bytes and unexpected discriminator sizes throw a `SolanaError` instead of decoding as the wrong account or instruction type. Generation fails when a field discriminator has no deterministic default or uses a value form the renderer cannot encode safely.
+
+Top-level instruction decoders require exact input consumption. Account decoders always reject truncated data, but accept unread trailing capacity unless the account declares a `sizeDiscriminatorNode`; size-discriminated accounts reject both truncation and suffix bytes.
+
+Optional instruction accounts use Codama's `programId` strategy by default. When an optional account is absent, the builder emits a readonly program-address placeholder so every later account keeps its declared index. The account slot is removed only when the instruction explicitly selects the legacy `omitted` strategy.
+
+### Scalar enums
 
 Scalar enums (all-empty variants) generate a Dart `enum` with index-based encoder/decoder:
 
@@ -154,7 +177,9 @@ Encoder<AccountStatus> getAccountStatusEncoder() { ... }
 Decoder<AccountStatus> getAccountStatusDecoder() { ... }
 ```
 
-### Data Enums (Discriminated Unions)
+The generated enum API is the same for `u8`, `u16`, `u32`, and `u64` discriminators. The renderer converts `u64` indices to and from `BigInt` at the codec boundary and rejects out-of-range discriminators before converting them to Dart enum indices.
+
+### Data enums (discriminated unions)
 
 Data enums generate Dart 3 `sealed class` hierarchies:
 
@@ -202,7 +227,7 @@ Future<(Address, int)> findMyPdaPda({
 }) async { ... }
 ```
 
-## Type Mapping
+## Type mapping
 
 | Codama Type                         | Dart Type       | Codec                            |
 | ----------------------------------- | --------------- | -------------------------------- |
@@ -237,7 +262,7 @@ Future<(Address, int)> findMyPdaPda({
 
 All naming conventions are customizable:
 
-```typescript
+```ts
 import { renderVisitor, createDartNameApi } from "codama-renderers-dart";
 
 const nameApi = {
@@ -248,7 +273,7 @@ const nameApi = {
 visit(root, renderVisitor("output", { nameApi }));
 ```
 
-## Target Packages
+## Target packages
 
 Generated Dart code depends on these solana_kit packages:
 
@@ -282,39 +307,10 @@ Key source files:
 ## Development
 
 ```bash
-# Install dependencies
-
-[![pub package](https://img.shields.io/pub/v/codama-renderers-dart.svg)](https://pub.dev/packages/codama-renderers-dart)
-[![CI](https://github.com/openbudgetfun/solana_kit/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/openbudgetfun/solana_kit/actions/workflows/ci.yml)
-[![Coverage](https://codecov.io/gh/openbudgetfun/solana_kit/branch/main/graph/badge.svg?flag=codama-renderers-dart)](https://codecov.io/gh/openbudgetfun/solana_kit?flag=codama-renderers-dart)
 pnpm install
-
-# Type check
-
-[![pub package](https://img.shields.io/pub/v/codama-renderers-dart.svg)](https://pub.dev/packages/codama-renderers-dart)
-[![CI](https://github.com/openbudgetfun/solana_kit/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/openbudgetfun/solana_kit/actions/workflows/ci.yml)
-[![Coverage](https://codecov.io/gh/openbudgetfun/solana_kit/branch/main/graph/badge.svg?flag=codama-renderers-dart)](https://codecov.io/gh/openbudgetfun/solana_kit?flag=codama-renderers-dart)
 npx tsc --noEmit
-
-# Run tests
-
-[![pub package](https://img.shields.io/pub/v/codama-renderers-dart.svg)](https://pub.dev/packages/codama-renderers-dart)
-[![CI](https://github.com/openbudgetfun/solana_kit/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/openbudgetfun/solana_kit/actions/workflows/ci.yml)
-[![Coverage](https://codecov.io/gh/openbudgetfun/solana_kit/branch/main/graph/badge.svg?flag=codama-renderers-dart)](https://codecov.io/gh/openbudgetfun/solana_kit?flag=codama-renderers-dart)
 pnpm test
-
-# Watch mode
-
-[![pub package](https://img.shields.io/pub/v/codama-renderers-dart.svg)](https://pub.dev/packages/codama-renderers-dart)
-[![CI](https://github.com/openbudgetfun/solana_kit/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/openbudgetfun/solana_kit/actions/workflows/ci.yml)
-[![Coverage](https://codecov.io/gh/openbudgetfun/solana_kit/branch/main/graph/badge.svg?flag=codama-renderers-dart)](https://codecov.io/gh/openbudgetfun/solana_kit?flag=codama-renderers-dart)
 pnpm test:watch
-
-# Build
-
-[![pub package](https://img.shields.io/pub/v/codama-renderers-dart.svg)](https://pub.dev/packages/codama-renderers-dart)
-[![CI](https://github.com/openbudgetfun/solana_kit/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/openbudgetfun/solana_kit/actions/workflows/ci.yml)
-[![Coverage](https://codecov.io/gh/openbudgetfun/solana_kit/branch/main/graph/badge.svg?flag=codama-renderers-dart)](https://codecov.io/gh/openbudgetfun/solana_kit?flag=codama-renderers-dart)
 pnpm build
 ```