# bindings.json

## Function

`bindings.json` Description extension The call surface exposed by BT scripts. It does not write business logic, but only declares entry functions, extended objects, object methods, parameter types, return types and object life cycle semantics.

What the script can call is completely determined by `bindings.json`; the extension backend must provide an implementation corresponding to bindings.

## Syntax

```json
{
    "api_version": 1,
    "functions": [
        {
            "name": "calc",
            "id": 1,
            "params": [
                { "name": "value", "type": "int" }
            ],
            "returns": "Calc"
        }
    ],
    "objects": [
        {
            "name": "Calc",
            "type_id": 1,
            "methods": [
                {
                    "name": "add",
                    "id": 2,
                    "params": [
                        { "name": "value", "type": "int" }
                    ],
                    "returns": "Calc"
                },
                {
                    "name": "value",
                    "id": 3,
                    "params": [],
                    "returns": "int"
                },
                {
                    "name": "close",
                    "id": 4,
                    "params": [],
                    "returns": "bool",
                    "lifecycle": "dispose"
                }
            ]
        }
    ]
}
```

## Parameters

| Field | Description |
| ------ | ------ |
| `api_version` | Must be consistent with `manifest.api_version`, use `1`. |
| `functions` | Public entry function list, at least one entry is required. |
| `functions[].name` | The global entry name seen in the script, such as `calc`. |
| `functions[].id` | Backend call ID, used by the WASM extension to distribute to specific handlers. |
| `functions[].params` | Parameter list. |
| `functions[].returns` | Return type, which can be a primitive type or an object type declared in `objects`. |
| `objects` | Extended object type list. |
| `objects[].name` | The object type name must start with a capital letter, such as `Calc`; `type(obj)` in the script will return this name. |
| `objects[].type_id` | Object type ID, cannot be `0`. |
| `objects[].methods` | List of object methods. |
| `methods[].lifecycle` | Method life cycle, default `call`, writable `dispose`. |

## Parameter type

bindings supports the following parameter types:

| Type | Description |
| ------ | ------ |
| `any` | Any BT value, only used for parameter declaration, suitable for extension methods such as `bind(value)` that need to receive multiple basic values. |
| `empty` | `empty` from BT. |
| `null` | `null` from BT. |
| `bool` | Boolean value. |
| `int` | Integer. |
| `float` | Floating point number. |
| `string` | String. |
| `bytes` | Bytes Binary bytes. |
| `array` | Array. |
| `object` | Ordinary object. |

The return type can use primitive types other than `any`, or it can use the object type name declared in `objects`. When the return type is declared as `object`, the extension can return a normal object or `empty` to indicate that there is no object result; when it is declared as a specific extended object type, the corresponding object handle must still be returned.

## Return Value

bindings themselves have no runtime return value. The actual return value of the extension is constrained by the `returns` field: if the original type is written, the runtime will verify the actual return value type; if the object type name is written, the runtime will require the corresponding extended object to be returned.

When the entry or method returns the extension object, the script can read the type name of the object declared in `objects[].name` through `type()`:

```bt
num = calc(1)

// Output: Calc
print type(num)
```

## Parameter role

The parameter defaults to a normal value:

```json
{ "name": "value", "type": "int" }
```

If the parameter is the path used by the WASM extension, you can declare `role`:

```json
{ "name": "input", "type": "string", "role": "path_read" }
```

 | role | Description |
| ------ | ------ |
| `value` | Normal value, no path processing is performed. |
| `path_read` | Read the file path, require `type` to be `string`, and declare `fs_read` in the `manifest.permissions` array. |
| `path_write` | Writes the file path, requires `type` to be `string`, and declares `fs_write` in the `manifest.permissions` array. |
| `path_dir` | Directory path, requires `type` to be `string`, and declares `fs_read` or `fs_write` in the `manifest.permissions` array. |

## Code Examples

 will give the script such a calling experience:

```bt
num = calc(1)
num.add(2)
value = num.value()

// Output: 3
print value
```

## Notes

- Entry names, method names, and parameter names must use snake_case and cannot start or end with an underscore.
- `id` cannot be repeated in the same bindings file and cannot be `0`.
- The object `type_id` cannot be `0` and cannot be repeated within the same extension.
 - `lifecycle: "dispose"` can only be used with the `close` or `dispose` method; the method cannot have parameters and the return type must be a primitive type.
-Pure BT extension requires that the entry functions and object methods in bindings have implementations with the same names in `src/lib.bt`.
- `type()` returns a script-visible type name and does not participate in extension method routing or security verification; the host still uses module ID and type ID to manage object identity.