[0.22] Add InstructionLinkNode, InstructionAccountLinkNode and `I…

…nstructionArgumentLinkNode` (#183)

Co-Authored-By: Danny Povolotski <[email protected]>

.changeset/hungry-hairs-shave.md

@@ -0,0 +1,11 @@
+---
+'@kinobi-so/renderers-js-umi': minor
+'@kinobi-so/renderers-rust': minor
+'@kinobi-so/visitors-core': minor
+'@kinobi-so/renderers-js': minor
+'@kinobi-so/node-types': minor
+'@kinobi-so/errors': minor
+'@kinobi-so/nodes': minor
+---
+
+Add `InstructionLinkNode`, `InstructionAccountLinkNode` and `InstructionArgumentLinkNode`

packages/errors/src/context.ts

@@ -75,7 +75,7 @@ export type KinobiErrorContext = DefaultUnspecifiedErrorContextToUndefined<{
         kind: LinkNode['kind'];
         linkNode: LinkNode;
         name: CamelCaseString;
-        program?: CamelCaseString;
+        stack: Node[];
     };
     [KINOBI_ERROR__NODE_FILESYSTEM_FUNCTION_UNAVAILABLE]: {
         fsFunction: string;

packages/node-types/src/linkNodes/InstructionAccountLinkNode.ts

@@ -0,0 +1,14 @@
+import type { CamelCaseString } from '../shared';
+import type { InstructionLinkNode } from './InstructionLinkNode';
+
+export interface InstructionAccountLinkNode<
+    TInstruction extends InstructionLinkNode | undefined = InstructionLinkNode | undefined,
+> {
+    readonly kind: 'instructionAccountLinkNode';
+
+    // Children.
+    readonly instruction?: TInstruction;
+
+    // Data.
+    readonly name: CamelCaseString;
+}

packages/node-types/src/linkNodes/InstructionArgumentLinkNode.ts

@@ -0,0 +1,14 @@
+import type { CamelCaseString } from '../shared';
+import type { InstructionLinkNode } from './InstructionLinkNode';
+
+export interface InstructionArgumentLinkNode<
+    TInstruction extends InstructionLinkNode | undefined = InstructionLinkNode | undefined,
+> {
+    readonly kind: 'instructionArgumentLinkNode';
+
+    // Children.
+    readonly instruction?: TInstruction;
+
+    // Data.
+    readonly name: CamelCaseString;
+}

packages/node-types/src/linkNodes/InstructionLinkNode.ts

@@ -0,0 +1,12 @@
+import type { CamelCaseString } from '../shared';
+import type { ProgramLinkNode } from './ProgramLinkNode';
+
+export interface InstructionLinkNode<TProgram extends ProgramLinkNode | undefined = ProgramLinkNode | undefined> {
+    readonly kind: 'instructionLinkNode';
+
+    // Children.
+    readonly program?: TProgram;
+
+    // Data.
+    readonly name: CamelCaseString;
+}

packages/node-types/src/linkNodes/LinkNode.ts

@@ -1,10 +1,20 @@
 import type { AccountLinkNode } from './AccountLinkNode';
 import type { DefinedTypeLinkNode } from './DefinedTypeLinkNode';
+import type { InstructionAccountLinkNode } from './InstructionAccountLinkNode';
+import type { InstructionArgumentLinkNode } from './InstructionArgumentLinkNode';
+import type { InstructionLinkNode } from './InstructionLinkNode';
 import type { PdaLinkNode } from './PdaLinkNode';
 import type { ProgramLinkNode } from './ProgramLinkNode';
 
 // Link Node Registration.
-export type RegisteredLinkNode = AccountLinkNode | DefinedTypeLinkNode | PdaLinkNode | ProgramLinkNode;
+export type RegisteredLinkNode =
+    | AccountLinkNode
+    | DefinedTypeLinkNode
+    | InstructionAccountLinkNode
+    | InstructionArgumentLinkNode
+    | InstructionLinkNode
+    | PdaLinkNode
+    | ProgramLinkNode;
 
 // Link Node Helpers.
 export type LinkNode = RegisteredLinkNode;

packages/node-types/src/linkNodes/index.ts

@@ -1,5 +1,8 @@
 export * from './AccountLinkNode';
 export * from './DefinedTypeLinkNode';
+export * from './InstructionAccountLinkNode';
+export * from './InstructionArgumentLinkNode';
+export * from './InstructionLinkNode';
 export * from './LinkNode';
 export * from './PdaLinkNode';
 export * from './ProgramLinkNode';

packages/nodes/README.md

@@ -61,6 +61,9 @@ Below are all of the available nodes and their documentation. Also note that you
 -   [`LinkNode`](./docs/linkNodes/README.md) (abstract)
     -   [`AccountLinkNode`](./docs/linkNodes/AccountLinkNode.md)
     -   [`DefinedTypeLinkNode`](./docs/linkNodes/DefinedTypeLinkNode.md)
+    -   [`InstructionAccountLinkNode`](./docs/linkNodes/InstructionAccountLinkNode.md)
+    -   [`InstructionArgumentLinkNode`](./docs/linkNodes/InstructionArgumentLinkNode.md)
+    -   [`InstructionLinkNode`](./docs/linkNodes/InstructionLinkNode.md)
     -   [`PdaLinkNode`](./docs/linkNodes/PdaLinkNode.md)
     -   [`ProgramLinkNode`](./docs/linkNodes/ProgramLinkNode.md)
 -   [`PdaSeedNode`](./docs/pdaSeedNodes/README.md) (abstract)

packages/nodes/docs/linkNodes/AccountLinkNode.md

@@ -21,7 +21,7 @@ This node represents a reference to an existing [`AccountNode`](../AccountNode.m
 
 ### `accountLinkNode(name, program?)`
 
-Helper function that creates a `AccountLinkNode` object from the name of the `AccountNode` we are referring to. If the account is from another program, the `program` parameter must be provided as either a `string` or a `ProgramLinkNode`.
+Helper function that creates an `AccountLinkNode` object from the name of the `AccountNode` we are referring to. If the account is from another program, the `program` parameter must be provided as either a `string` or a `ProgramLinkNode`.
 
 ```ts
 const node = accountLinkNode('myAccount');

packages/nodes/docs/linkNodes/InstructionAccountLinkNode.md

@@ -0,0 +1,38 @@
+# `InstructionAccountLinkNode`
+
+This node represents a reference to an existing [`InstructionAccountNode`](../InstructionAccountNode.md) in the Kinobi IDL.
+
+## Attributes
+
+### Data
+
+| Attribute | Type                           | Description                                                                                   |
+| --------- | ------------------------------ | --------------------------------------------------------------------------------------------- |
+| `kind`    | `"instructionAccountLinkNode"` | The node discriminator.                                                                       |
+| `name`    | `CamelCaseString`              | The name of the [`InstructionAccountNode`](../InstructionAccountNode.md) we are referring to. |
+
+### Children
+
+| Attribute     | Type                                              | Description                                                                                                                                                                                          |
+| ------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `instruction` | [`InstructionLinkNode`](./InstructionLinkNode.md) | (Optional) The instruction associated with the linked account. Default to using the instruction we are currently under. Note that the instruction itself can point to a different program is needed. |
+
+## Functions
+
+### `instructionAccountLinkNode(name, instruction?)`
+
+Helper function that creates an `InstructionAccountLinkNode` object from the name of the `InstructionAccountNode` we are referring to. If the account is from another instruction, the `instruction` parameter must be provided as either a `string` or a `InstructionLinkNode`. When providing an `InstructionLinkNode`, we can also provide a `ProgramLinkNode` to point to a different program.
+
+```ts
+// Links to an account in the current instruction.
+const node = instructionAccountLinkNode('myAccount');
+
+// Links to an account in another instruction but within the same program.
+const nodeFromAnotherInstruction = instructionAccountLinkNode('myAccount', 'myOtherInstruction');
+
+// Links to an account in another instruction from another program.
+const nodeFromAnotherProgram = instructionAccountLinkNode(
+    'myAccount',
+    instructionLinkNode('myOtherInstruction', 'myOtherProgram'),
+);
+```

packages/nodes/docs/linkNodes/InstructionArgumentLinkNode.md

@@ -0,0 +1,38 @@
+# `InstructionArgumentLinkNode`
+
+This node represents a reference to an existing [`InstructionArgumentNode`](../InstructionArgumentNode.md) in the Kinobi IDL.
+
+## Attributes
+
+### Data
+
+| Attribute | Type                            | Description                                                                                     |
+| --------- | ------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `kind`    | `"instructionArgumentLinkNode"` | The node discriminator.                                                                         |
+| `name`    | `CamelCaseString`               | The name of the [`InstructionArgumentNode`](../InstructionArgumentNode.md) we are referring to. |
+
+### Children
+
+| Attribute     | Type                                              | Description                                                                                                                                                                                           |
+| ------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `instruction` | [`InstructionLinkNode`](./InstructionLinkNode.md) | (Optional) The instruction associated with the linked argument. Default to using the instruction we are currently under. Note that the instruction itself can point to a different program is needed. |
+
+## Functions
+
+### `instructionArgumentLinkNode(name, instruction?)`
+
+Helper function that creates an `InstructionArgumentLinkNode` object from the name of the `InstructionArgumentNode` we are referring to. If the argument is from another instruction, the `instruction` parameter must be provided as either a `string` or a `InstructionLinkNode`. When providing an `InstructionLinkNode`, we can also provide a `ProgramLinkNode` to point to a different program.
+
+```ts
+// Links to an argument in the current instruction.
+const node = instructionArgumentLinkNode('myArgument');
+
+// Links to an argument in another instruction but within the same program.
+const nodeFromAnotherInstruction = instructionArgumentLinkNode('myArgument', 'myOtherInstruction');
+
+// Links to an argument in another instruction from another program.
+const nodeFromAnotherProgram = instructionArgumentLinkNode(
+    'myArgument',
+    instructionLinkNode('myOtherInstruction', 'myOtherProgram'),
+);
+```

packages/nodes/docs/linkNodes/InstructionLinkNode.md

@@ -0,0 +1,29 @@
+# `InstructionLinkNode`
+
+This node represents a reference to an existing [`InstructionNode`](../InstructionNode.md) in the Kinobi IDL.
+
+## Attributes
+
+### Data
+
+| Attribute | Type                    | Description                                                                     |
+| --------- | ----------------------- | ------------------------------------------------------------------------------- |
+| `kind`    | `"instructionLinkNode"` | The node discriminator.                                                         |
+| `name`    | `CamelCaseString`       | The name of the [`InstructionNode`](../InstructionNode.md) we are referring to. |
+
+### Children
+
+| Attribute | Type                                      | Description                                                                                                         |
+| --------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `program` | [`ProgramLinkNode`](./ProgramLinkNode.md) | (Optional) The program associated with the linked instruction. Default to using the program we are currently under. |
+
+## Functions
+
+### `instructionLinkNode(name, program?)`
+
+Helper function that creates an `InstructionLinkNode` object from the name of the `InstructionNode` we are referring to. If the instruction is from another program, the `program` parameter must be provided as either a `string` or a `ProgramLinkNode`.
+
+```ts
+const node = instructionLinkNode('myInstruction');
+const nodeFromAnotherProgram = instructionLinkNode('myInstruction', 'myOtherProgram');
+```

packages/nodes/docs/linkNodes/README.md

@@ -4,5 +4,8 @@ The `LinkNode` type helper represents all nodes that link to other nodes. Note t
 
 -   [`AccountLinkNode`](./AccountLinkNode.md)
 -   [`DefinedTypeLinkNode`](./DefinedTypeLinkNode.md)
+-   [`InstructionAccountLinkNode`](./InstructionAccountLinkNode.md)
+-   [`InstructionArgumentLinkNode`](./InstructionArgumentLinkNode.md)
+-   [`InstructionLinkNode`](./InstructionLinkNode.md)
 -   [`PdaLinkNode`](./PdaLinkNode.md)
 -   [`ProgramLinkNode`](./ProgramLinkNode.md)

packages/nodes/src/linkNodes/InstructionAccountLinkNode.ts

@@ -0,0 +1,21 @@
+import type { InstructionAccountLinkNode, InstructionLinkNode } from '@kinobi-so/node-types';
+
+import { camelCase } from '../shared';
+import { instructionLinkNode } from './InstructionLinkNode';
+
+export function instructionAccountLinkNode(
+    name: string,
+    instruction?: InstructionLinkNode | string,
+): InstructionAccountLinkNode {
+    return Object.freeze({
+        kind: 'instructionAccountLinkNode',
+
+        // Children.
+        ...(instruction === undefined
+            ? {}
+            : { instruction: typeof instruction === 'string' ? instructionLinkNode(instruction) : instruction }),
+
+        // Data.
+        name: camelCase(name),
+    });
+}

packages/nodes/src/linkNodes/InstructionArgumentLinkNode.ts

@@ -0,0 +1,21 @@
+import type { InstructionArgumentLinkNode, InstructionLinkNode } from '@kinobi-so/node-types';
+
+import { camelCase } from '../shared';
+import { instructionLinkNode } from './InstructionLinkNode';
+
+export function instructionArgumentLinkNode(
+    name: string,
+    instruction?: InstructionLinkNode | string,
+): InstructionArgumentLinkNode {
+    return Object.freeze({
+        kind: 'instructionArgumentLinkNode',
+
+        // Children.
+        ...(instruction === undefined
+            ? {}
+            : { instruction: typeof instruction === 'string' ? instructionLinkNode(instruction) : instruction }),
+
+        // Data.
+        name: camelCase(name),
+    });
+}

packages/nodes/src/linkNodes/InstructionLinkNode.ts

@@ -0,0 +1,16 @@
+import type { InstructionLinkNode, ProgramLinkNode } from '@kinobi-so/node-types';
+
+import { camelCase } from '../shared';
+import { programLinkNode } from './ProgramLinkNode';
+
+export function instructionLinkNode(name: string, program?: ProgramLinkNode | string): InstructionLinkNode {
+    return Object.freeze({
+        kind: 'instructionLinkNode',
+
+        // Children.
+        ...(program === undefined ? {} : { program: typeof program === 'string' ? programLinkNode(program) : program }),
+
+        // Data.
+        name: camelCase(name),
+    });
+}

packages/nodes/src/linkNodes/LinkNode.ts

@@ -1,9 +1,12 @@
 // Link Node Registration.
 export const REGISTERED_LINK_NODE_KINDS = [
-    'programLinkNode' as const,
-    'pdaLinkNode' as const,
     'accountLinkNode' as const,
     'definedTypeLinkNode' as const,
+    'instructionAccountLinkNode' as const,
+    'instructionArgumentLinkNode' as const,
+    'instructionLinkNode' as const,
+    'pdaLinkNode' as const,
+    'programLinkNode' as const,
 ];
 
 // Link Node Helpers.

packages/nodes/src/linkNodes/index.ts

@@ -1,5 +1,8 @@
 export * from './AccountLinkNode';
 export * from './DefinedTypeLinkNode';
+export * from './InstructionAccountLinkNode';
+export * from './InstructionArgumentLinkNode';
+export * from './InstructionLinkNode';
 export * from './LinkNode';
 export * from './PdaLinkNode';
 export * from './ProgramLinkNode';

packages/nodes/test/linkNodes/InstructionAccountLinkNode.test.ts

@@ -0,0 +1,13 @@
+import { expect, test } from 'vitest';
+
+import { instructionAccountLinkNode } from '../../src';
+
+test('it returns the right node kind', () => {
+    const node = instructionAccountLinkNode('mint');
+    expect(node.kind).toBe('instructionAccountLinkNode');
+});
+
+test('it returns a frozen object', () => {
+    const node = instructionAccountLinkNode('mint');
+    expect(Object.isFrozen(node)).toBe(true);
+});

packages/nodes/test/linkNodes/InstructionArgumentLinkNode.test.ts

@@ -0,0 +1,13 @@
+import { expect, test } from 'vitest';
+
+import { instructionArgumentLinkNode } from '../../src';
+
+test('it returns the right node kind', () => {
+    const node = instructionArgumentLinkNode('amount');
+    expect(node.kind).toBe('instructionArgumentLinkNode');
+});
+
+test('it returns a frozen object', () => {
+    const node = instructionArgumentLinkNode('amount');
+    expect(Object.isFrozen(node)).toBe(true);
+});

packages/nodes/test/linkNodes/InstructionLinkNode.test.ts

@@ -0,0 +1,13 @@
+import { expect, test } from 'vitest';
+
+import { instructionLinkNode } from '../../src';
+
+test('it returns the right node kind', () => {
+    const node = instructionLinkNode('transferTokens');
+    expect(node.kind).toBe('instructionLinkNode');
+});
+
+test('it returns a frozen object', () => {
+    const node = instructionLinkNode('transferTokens');
+    expect(Object.isFrozen(node)).toBe(true);
+});