Add node documentation — Part 5: Other nodes (#101)

packages/nodes/docs/template.md → packages/nodes/docs/_template.md

@@ -1,6 +1,6 @@
 # `SomeNode`
 
-Some node description.
+This node represents TODO.
 
 ## Attributes
 
@@ -14,9 +14,9 @@ Some node description.
 
 ### Children
 
-| Attribute | Type                                | Description             |
-| --------- | ----------------------------------- | ----------------------- |
-| `child`   | [`TypeNode`](./typeNodes/README.md) | The child of some node. |
+| Attribute | Type                                 | Description             |
+| --------- | ------------------------------------ | ----------------------- |
+| `child`   | [`TypeNode`](../typeNodes/README.md) | The child of some node. |
 
 OR
 

packages/nodes/docs/countNodes/FixedCountNode.md

@@ -0,0 +1,34 @@
+# `FixedCountNode`
+
+A node that represents a count strategy where **the number of items is known and fixed**. This enables nodes such as [`ArrayTypeNode`](../typeNodes/ArrayTypeNode.md) to represent arrays of a fixed length.
+
+## Attributes
+
+### Data
+
+| Attribute | Type               | Description               |
+| --------- | ------------------ | ------------------------- |
+| `kind`    | `"fixedCountNode"` | The node discriminator.   |
+| `value`   | `number`           | The fixed count of items. |
+
+### Children
+
+_This node has no children._
+
+## Functions
+
+### `fixedCountNode(value)`
+
+Helper function that creates a `FixedCountNode` object from a number.
+
+```ts
+const node = fixedCountNode(42);
+```
+
+## Examples
+
+### An array of three public keys
+
+```ts
+arrayTypeNode(publicKeyTypeNode(), fixedCountNode(3));
+```

packages/nodes/docs/countNodes/PrefixedCountNode.md

@@ -0,0 +1,35 @@
+# `PrefixedCountNode`
+
+A node that represents a count strategy where **the number of items is stored as a number prefix**. This enables nodes such as [`ArrayTypeNode`](../typeNodes/ArrayTypeNode.md) to represent arrays such that their length is stored as a prefix.
+
+## Attributes
+
+### Data
+
+| Attribute | Type                  | Description             |
+| --------- | --------------------- | ----------------------- |
+| `kind`    | `"prefixedCountNode"` | The node discriminator. |
+
+### Children
+
+| Attribute | Type                                                                                                   | Description                                   |
+| --------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------- |
+| `prefix`  | [`NestedTypeNode`](../typeNodes/NestedTypeNode.md)<[`NumberTypeNode`](../typeNodes/NumberTypeNode.md)> | The node that determines the number of items. |
+
+## Functions
+
+### `prefixedCountNode(prefix)`
+
+Helper function that creates a `PrefixedCountNode` object from a number node.
+
+```ts
+const node = prefixedCountNode(numberTypeNode(u32));
+```
+
+## Examples
+
+### An variable array of public keys prefixed with a u32
+
+```ts
+arrayTypeNode(publicKeyTypeNode(), prefixedCountNode(numberTypeNode(u32)));
+```

packages/nodes/docs/countNodes/README.md

@@ -0,0 +1,7 @@
+# `CountNode` (abstract)
+
+The `CountNode` type helper represents all available strategies that determine the size of a collection. Note that `CountNode` is a type alias and cannot be used directly as a node. Instead you may use one of the following nodes:
+
+-   [`FixedCountNode`](./FixedCountNode.md)
+-   [`PrefixedCountNode`](./PrefixedCountNode.md)
+-   [`RemainderCountNode`](./RemainderCountNode.md)

packages/nodes/docs/countNodes/RemainderCountNode.md

@@ -0,0 +1,35 @@
+# `RemainderCountNode`
+
+A node that represents a count strategy where **the number of items is unknown and inferred by the remainder of the bytes**. When encoding, the items are encoded as-is without storing the total count. When decoding, items are decoded one by one until the end of the buffer is reached.
+
+This enables nodes such as [`ArrayTypeNode`](../typeNodes/ArrayTypeNode.md) to represent variable arrays at the end of buffers.
+
+## Attributes
+
+### Data
+
+| Attribute | Type                   | Description             |
+| --------- | ---------------------- | ----------------------- |
+| `kind`    | `"remainderCountNode"` | The node discriminator. |
+
+### Children
+
+_This node has no children._
+
+## Functions
+
+### `remainderCountNode()`
+
+Helper function that creates a `RemainderCountNode` object.
+
+```ts
+const node = remainderCountNode();
+```
+
+## Examples
+
+### A remainder array of public keys
+
+```ts
+arrayTypeNode(publicKeyTypeNode(), remainderCountNode());
+```

packages/nodes/docs/discriminatorNodes/ConstantDiscriminatorNode.md

@@ -0,0 +1,48 @@
+# `ConstantDiscriminatorNode`
+
+This node represents a byte discrimination strategy where the data is **identified by a constant value** at a given offset. Discriminator nodes are used to distinguish between different types of accounts or instructions in a program.
+
+## Attributes
+
+### Data
+
+| Attribute | Type                          | Description                                       |
+| --------- | ----------------------------- | ------------------------------------------------- |
+| `kind`    | `"constantDiscriminatorNode"` | The node discriminator.                           |
+| `offset`  | `number`                      | The byte at which the constant should be located. |
+
+### Children
+
+| Attribute  | Type                                                     | Description                                  |
+| ---------- | -------------------------------------------------------- | -------------------------------------------- |
+| `constant` | [`ConstantValueNode`](./valueNodes/ConstantValueNode.md) | The constant value that identifies the data. |
+
+## Functions
+
+### `constantDiscriminatorNode(constant, offset?)`
+
+Helper function that creates a `ConstantDiscriminatorNode` object from a constant value node and an optional offset.
+
+```ts
+const node = constantDiscriminatorNode(constantValueNodeFromString('utf8', 'Hello'), 64);
+```
+
+## Examples
+
+### An account distinguished by a u32 number equal to 42 at offset 0
+
+```ts
+accountNode({
+    discriminators: [constantDiscriminatorNode(constantValueNode(numberTypeNode('u32'), numberValueNode(42)))],
+    // ...
+});
+```
+
+### An instruction disctinguished by an 8-byte hash at offset 0
+
+```ts
+instructionNode({
+    discriminators: [constantValueNodeFromBytes('base16', '0011223344556677')],
+    // ...
+});
+```

packages/nodes/docs/discriminatorNodes/FieldDiscriminatorNode.md

@@ -0,0 +1,65 @@
+# `FieldDiscriminatorNode`
+
+This node represents a byte discrimination strategy where the data is **identified by the default value of a struct field** at a given offset. Discriminator nodes are used to distinguish between different types of accounts or instructions in a program.
+
+## Attributes
+
+### Data
+
+| Attribute | Type                       | Description                                                                                                      |
+| --------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `kind`    | `"fieldDiscriminatorNode"` | The node discriminator.                                                                                          |
+| `field`   | `CamelCaseString`          | The name of the [`StructFieldTypeNode`](../typeNodes/StructFieldTypeNode.md) we should use to identify the data. |
+| `offset`  | `number`                   | The byte at which the field should be located.                                                                   |
+
+### Children
+
+_This node has no children._
+
+## Functions
+
+### `fieldDiscriminatorNode(field, offset?)`
+
+Helper function that creates a `FieldDiscriminatorNode` object from a field name and an optional offset.
+
+```ts
+const node = fieldDiscriminatorNode('accountState', 64);
+```
+
+## Examples
+
+### An account distinguished by a u32 field at offset 0
+
+```ts
+accountNode({
+    data: structTypeNode([
+        structFieldTypeNode({
+            name: 'discriminator',
+            type: numberTypeNode('u32'),
+            defaultValue: numberValueNode(42),
+            defaultValueStrategy: 'omitted',
+        }),
+        // ...
+    ]),
+    discriminators: [fieldDiscriminatorNode('discriminator')],
+    // ...
+});
+```
+
+### An instruction disctinguished by an 8-byte argument at offset 0
+
+```ts
+instructionNode({
+    arguments: [
+        instructionArgumentNode({
+            name: 'discriminator',
+            type: fixedSizeTypeNode(bytesTypeNode(), 8),
+            defaultValue: bytesValueNode('base16', '0011223344556677'),
+            defaultValueStrategy: 'omitted',
+        }),
+        // ...
+    ],
+    discriminators: [fieldDiscriminatorNode('discriminator')],
+    // ...
+});
+```

packages/nodes/docs/discriminatorNodes/README.md

@@ -0,0 +1,7 @@
+# `DiscriminatorNode` (abstract)
+
+The `DiscriminatorNode` type helper represents all available strategies that help distinguish blocks of data — such as accounts and instructions. Note that `DiscriminatorNode` is a type alias and cannot be used directly as a node. Instead you may use one of the following nodes:
+
+-   [`ConstantDiscriminatorNode`](./ConstantDiscriminatorNode.md)
+-   [`FieldDiscriminatorNode`](./FieldDiscriminatorNode.md)
+-   [`SizeDiscriminatorNode`](./SizeDiscriminatorNode.md)

packages/nodes/docs/discriminatorNodes/SizeDiscriminatorNode.md

@@ -0,0 +1,46 @@
+# `SizeDiscriminatorNode`
+
+This node represents a byte discrimination strategy where the data is **identified by being equal to a given size**. Discriminator nodes are used to distinguish between different types of accounts or instructions in a program.
+
+## Attributes
+
+### Data
+
+| Attribute | Type                      | Description                        |
+| --------- | ------------------------- | ---------------------------------- |
+| `kind`    | `"sizeDiscriminatorNode"` | The node discriminator.            |
+| `size`    | `number`                  | The size that identifies the data. |
+
+### Children
+
+_This node has no children._
+
+## Functions
+
+### `sizeDiscriminatorNode(size)`
+
+Helper function that creates a `SizeDiscriminatorNode` object from a size.
+
+```ts
+const node = sizeDiscriminatorNode(165);
+```
+
+## Examples
+
+### An account distinguished by its size being equal to 42
+
+```ts
+accountNode({
+    discriminators: [sizeDiscriminatorNode(42)],
+    // ...
+});
+```
+
+### An instruction disctinguished by its size being equal to 42
+
+```ts
+instructionNode({
+    discriminators: [sizeDiscriminatorNode(42)],
+    // ...
+});
+```

packages/nodes/docs/linkNodes/AccountLinkNode.md

@@ -0,0 +1,27 @@
+# `AccountLinkNode`
+
+This node represents a reference to an existing [`AccountNode`](../AccountNode.md) in the Kinobi IDL.
+
+## Attributes
+
+### Data
+
+| Attribute    | Type                | Description                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| ------------ | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `kind`       | `"accountLinkNode"` | The node discriminator.                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `name`       | `CamelCaseString`   | The name of the [`AccountNode`](../AccountNode.md) we are referring to.                                                                                                                                                                                                                                                                                                                                                           |
+| `importFrom` | `CamelCaseString`   | (Optional) The reference of the module we are importing from or `"hooked"` if the account is defined in the same module but manually written when rendering clients. Default to referrencing directly from the Kinobi IDL instead of using an external referrence. Note that this information is only used for rendering clients. This, it will likely be removed from the Kinobi IDL and pushed to the renderer options instead. |
+
+### Children
+
+_This node has no children._
+
+## Functions
+
+### `accountLinkNode(name, importFrom?)`
+
+Helper function that creates a `AccountLinkNode` object from the name of the `AccountNode` we are referring to.
+
+```ts
+const node = accountLinkNode('myAccount');
+```

packages/nodes/docs/linkNodes/DefinedTypeLinkNode.md

@@ -0,0 +1,27 @@
+# `DefinedTypeLinkNode`
+
+This node represents a reference to an existing [`DefinedTypeNode`](../DefinedTypeNode.md) in the Kinobi IDL.
+
+## Attributes
+
+### Data
+
+| Attribute    | Type                    | Description                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `kind`       | `"definedTypeLinkNode"` | The node discriminator.                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `name`       | `CamelCaseString`       | The name of the [`DefinedTypeNode`](../DefinedTypeNode.md) we are referring to.                                                                                                                                                                                                                                                                                                                                                |
+| `importFrom` | `CamelCaseString`       | (Optional) The reference of the module we are importing from or `"hooked"` if the type is defined in the same module but manually written when rendering clients. Default to referrencing directly from the Kinobi IDL instead of using an external referrence. Note that this information is only used for rendering clients. This, it will likely be removed from the Kinobi IDL and pushed to the renderer options instead. |
+
+### Children
+
+_This node has no children._
+
+## Functions
+
+### `definedTypeLinkNode(name, importFrom?)`
+
+Helper function that creates a `DefinedTypeLinkNode` object from the name of the `DefinedTypeNode` we are referring to.
+
+```ts
+const node = definedTypeLinkNode('myDefinedType');
+```

packages/nodes/docs/linkNodes/PdaLinkNode.md

@@ -0,0 +1,27 @@
+# `PdaLinkNode`
+
+This node represents a reference to an existing [`PdaNode`](../PdaNode.md) in the Kinobi IDL.
+
+## Attributes
+
+### Data
+
+| Attribute    | Type              | Description                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| ------------ | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `kind`       | `"pdaLinkNode"`   | The node discriminator.                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `name`       | `CamelCaseString` | The name of the [`PdaNode`](../PdaNode.md) we are referring to.                                                                                                                                                                                                                                                                                                                                                               |
+| `importFrom` | `CamelCaseString` | (Optional) The reference of the module we are importing from or `"hooked"` if the PDA is defined in the same module but manually written when rendering clients. Default to referrencing directly from the Kinobi IDL instead of using an external referrence. Note that this information is only used for rendering clients. This, it will likely be removed from the Kinobi IDL and pushed to the renderer options instead. |
+
+### Children
+
+_This node has no children._
+
+## Functions
+
+### `pdaLinkNode(name, importFrom?)`
+
+Helper function that creates a `PdaLinkNode` object from the name of the `PdaNode` we are referring to.
+
+```ts
+const node = pdaLinkNode('myPda');
+```

packages/nodes/docs/linkNodes/ProgramLinkNode.md

@@ -0,0 +1,27 @@
+# `ProgramLinkNode`
+
+This node represents a reference to an existing [`ProgramNode`](../ProgramNode.md) in the Kinobi IDL.
+
+## Attributes
+
+### Data
+
+| Attribute    | Type                | Description                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| ------------ | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `kind`       | `"programLinkNode"` | The node discriminator.                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `name`       | `CamelCaseString`   | The name of the [`ProgramNode`](../ProgramNode.md) we are referring to.                                                                                                                                                                                                                                                                                                                                                           |
+| `importFrom` | `CamelCaseString`   | (Optional) The reference of the module we are importing from or `"hooked"` if the program is defined in the same module but manually written when rendering clients. Default to referrencing directly from the Kinobi IDL instead of using an external referrence. Note that this information is only used for rendering clients. This, it will likely be removed from the Kinobi IDL and pushed to the renderer options instead. |
+
+### Children
+
+_This node has no children._
+
+## Functions
+
+### `programLinkNode(name, importFrom?)`
+
+Helper function that creates a `ProgramLinkNode` object from the name of the `ProgramNode` we are referring to.
+
+```ts
+const node = programLinkNode('myProgram');
+```

packages/nodes/docs/linkNodes/README.md

@@ -0,0 +1,8 @@
+# `LinkNode` (abstract)
+
+The `LinkNode` type helper represents all nodes that link to other nodes. Note that `LinkNode` is a type alias and cannot be used directly as a node. Instead you may use one of the following nodes:
+
+-   [`AccountLinkNode`](./AccountLinkNode.md)
+-   [`DefinedTypeLinkNode`](./DefinedTypeLinkNode.md)
+-   [`PdaLinkNode`](./PdaLinkNode.md)
+-   [`ProgramLinkNode`](./ProgramLinkNode.md)

packages/nodes/docs/pdaSeedNodes/ConstantPdaSeedNode.md

@@ -0,0 +1,61 @@
+# `ConstantPdaSeedNode`
+
+This node represents a constant seed for a program-derived address (PDA).
+
+## Attributes
+
+### Data
+
+| Attribute | Type                    | Description             |
+| --------- | ----------------------- | ----------------------- |
+| `kind`    | `"constantPdaSeedNode"` | The node discriminator. |
+
+### Children
+
+| Attribute | Type                                                                                                            | Description                     |
+| --------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------- |
+| `type`    | [`TypeNode`](../typeNodes/README.md)                                                                            | The type of the constant seed.  |
+| `value`   | [`ValueNode`](../valueNodes/README.md) \| [`ProgramIdValueNode`](../contextualValueNodes/ProgramIdValueNode.md) | The value of the constant seed. |
+
+## Functions
+
+### `constantPdaSeedNode(type, value)`
+
+Helper function that creates a `ConstantPdaSeedNode` object from a type node and a value node.
+
+```ts
+const node = constantPdaSeedNode(numberTypeNode('u32'), numberValueNode(42));
+```
+
+### `constantPdaSeedNodeFromString(encoding, data)`
+
+Helper function that creates a `ConstantPdaSeedNode` object of type `StringTypeNode` from an encoding and a string of data.
+
+```ts
+constantPdaSeedNodeFromString('utf8', 'Hello');
+
+// Equivalent to:
+constantPdaSeedNode(stringTypeNode('utf8'), stringValueNode('Hello'));
+```
+
+### `constantValueNodeFromBytes(encoding, data)`
+
+Helper function that creates a `ConstantValueNode` object of type `BytesTypeNode` from an encoding and a string of data.
+
+```ts
+constantValueNodeFromBytes('base16', 'FF99CC');
+
+// Equivalent to:
+constantValueNode(bytesTypeNode(), bytesValueNode('base16', 'FF99CC'));
+```
+
+## Examples
+
+### A PDA node with a UTF-8 constant seed
+
+```ts
+pdaNode({
+    name: 'tickets',
+    seeds: [constantPdaSeedNodeFromString('utf8', 'tickets')],
+});
+```

packages/nodes/docs/pdaSeedNodes/README.md

@@ -0,0 +1,6 @@
+# `PdaSeedNode` (abstract)
+
+The `PdaSeedNode` type helper represents all ways to define a PDA seed. Note that `PdaSeedNode` is a type alias and cannot be used directly as a node. Instead you may use one of the following nodes:
+
+-   [`ConstantPdaSeedNode`](./ConstantPdaSeedNode.md)
+-   [`VariablePdaSeedNode`](./VariablePdaSeedNode.md)

packages/nodes/docs/pdaSeedNodes/VariablePdaSeedNode.md

@@ -0,0 +1,40 @@
+# `VariablePdaSeedNode`
+
+This node represents a variable seed for a program-derived address (PDA). It is characterized by a name and a type.
+
+## Attributes
+
+### Data
+
+| Attribute | Type                    | Description                                   |
+| --------- | ----------------------- | --------------------------------------------- |
+| `kind`    | `"variablePdaSeedNode"` | The node discriminator.                       |
+| `name`    | `CamelCaseString`       | The name of the variable seed.                |
+| `docs`    | `string[]`              | Markdown documentation for the variable seed. |
+
+### Children
+
+| Attribute | Type                                 | Description                    |
+| --------- | ------------------------------------ | ------------------------------ |
+| `type`    | [`TypeNode`](../typeNodes/README.md) | The type of the variable seed. |
+
+## Functions
+
+### `variablePdaSeedNode(name, type, docs?)`
+
+Helper function that creates a `VariablePdaSeedNode` object from a name, a type node and optional documentation.
+
+```ts
+const node = variablePdaSeedNode('amount', numberTypeNode('u32'));
+```
+
+## Examples
+
+### A PDA node with a public key variable seed
+
+```ts
+pdaNode({
+    name: 'ticket',
+    seeds: [variablePdaSeedNode('authority', publicKeyTypeNode())],
+});
+```