Codama Documentation

A Fragment is a building block used by Codama renderers to compose generated source code. It solves the problem of managing code snippets and their dependencies simultaneously.

Instead of just a string, a fragment carries:

1. content: The actual source code string.
2. imports: (In flavored fragments) An ImportMap that tracks the symbolic dependencies required by the content.

When fragments are interpolated into one another using the fragment tagged template, the imports propagate upwards automatically. This allows you to build small pieces (like a single field) and compose them into larger structures (like a struct or a file) without manually threading import statements through every helper function.

import { fragment, use } from '@codama/fragments/javascript';

const pubkey = use('type Address', '@solana/kit');
const interfaceFragment = fragment`
export interface Account {
    readonly owner: ${pubkey};
}
`;

console.log(interfaceFragment.content);
// export interface Account {
//     readonly owner: Address;
// }

console.log(interfaceFragment.imports);
// Map { '@solana/kit' => Map { 'Address' => { ..., isType: true } } }

A LinkableDictionary allows you to store and access linkable nodes (like ProgramNodes, AccountNodes, or PdaNodes) via their link nodes.

To use it effectively:

1. Use recordLinkablesOnFirstVisitVisitor to populate the dictionary before any nodes are visited.
2. Use recordNodeStackVisitor to keep track of the current path.
3. Use the dictionary methods to resolve links to their actual nodes.

const linkables = new LinkableDictionary();

// Record linkable nodes via their full path.
linkables.recordPath([rootNode, programNode, accountNode]);

// Get a linkable node using the full path of a link node
const programNode: ProgramNode | undefined = linkables.get([...somePath, programLinkNode]);

// Get a linkable node or throw if not found
const programNode: ProgramNode = linkables.getOrThrow([...somePath, programLinkNode]);

// Get the path of a linkable node
const accountPath: NodePath<AccountNode> | undefined = linkables.getPath([...somePath, accountLinkNode]);

// Get the path of a linkable node or throw if not found
const accountPath: NodePath<AccountNode> = linkables.getPathOrThrow([...somePath, accountLinkNode]);

Visitors are the core building blocks of Codama scripts. You can reference them in your configuration using several patterns:

1. Import Paths

Visitors must be provided via an import path (local or NPM package). By default, the default export is used.

• Local: './my-visitor.js' or '/abs/path/to/visitor.js'
• Package: 'some-library' or '@acme/some-library'

To import a named export, append # followed by the name:

• './my-visitor.js#myExport'
• '@acme/some-library#myExport'

2. Visitors with Arguments

If a visitor is a function that accepts arguments, use an object instead of a string:

• from (string): The import path (and optional #export).
• args (array): Arguments to pass to the visitor function.

{
    "from": "@acme/some-library#myExport",
    "args": ["hello", { "someOption": true }]
}

3. Chaining and Transformation

If a visitor returns a new RootNode, that new node is passed to the next visitor in the chain. This allows you to transform the IDL in stages.

export default {
    scripts: {
        documentation: [
            './delete-all-accounts.js', // Returns IDL without accounts
            './generate-documentation.js', // Operates on the modified IDL
        ],
    },
};

When building a renderer, the recommended pattern is to create a visitor that traverses the Codama IDL and returns a RenderMap. This allows for testing the logic without filesystem side effects.

1. Testable approach: Use a visitor that returns a RenderMap (e.g., Visitor<RenderMap>).
2. Writing to disk: Wrap that visitor in writeRenderMapVisitor(visitor, baseDir) to execute the write.
3. High-level approach: For production renderers, provide a visitor that handles directory cleanup (e.g., using deleteDirectory) before writing.

import { deleteDirectory } from '@codama/renderers-core';
import { rootNodeVisitor, visit } from '@codama/visitors-core';

// Example of a high-level renderer setup
export function renderVisitor(path: string, options: { deleteFolderBeforeRendering?: boolean } = {}) {
    return rootNodeVisitor(async root => {
        if (options.deleteFolderBeforeRendering ?? true) {
            deleteDirectory(path);
        }
        // Assuming getRenderMapVisitor() is your core logic
        visit(root, writeRenderMapVisitor(getRenderMapVisitor(), path));
    });
}