File Utilities
This section covers low-level utility functions for discovering, reading, and writing blocklet.yml files directly on the filesystem. These functions provide the foundational tools for interacting with Blocklet metadata at the file level.
list#
A constant array containing the standard, acceptable names for Blocklet metadata files.
Type: string[]
Example
import { list } from '@blocklet/meta';
console.log(list);
// Expected output: ['blocklet.yml', 'blocklet.yaml']select(dir, [options])#
Locates the appropriate metadata file (blocklet.yml or blocklet.yaml) within a specified directory. By default, it will throw an error if no file is found.
Parameters
Name | Type | Description |
|---|---|---|
|
| The directory to search for the metadata file. |
|
| Optional. A configuration object. |
|
| Optional. If |
Returns
Type | Description |
|---|---|
| The full path to the found metadata file, or an empty string if not found and |
Example
import { select } from '@blocklet/meta';
const blockletDir = '/path/to/your/blocklet';
try {
const metaFilePath = select(blockletDir);
console.log(`Found metadata file at: ${metaFilePath}`);
} catch (error) {
console.error(error.message);
// If the file doesn't exist, this will log:
// 'blocklet.yml not found, please migrate your blocklet meta by run `abtnode blocklet:migrate`'
}
// Example without throwing an error
const nonExistentDir = '/path/to/nothing';
const metaFileOrEmpty = select(nonExistentDir, { throwOnError: false });
if (!metaFileOrEmpty) {
console.log('No metadata file found, and no error was thrown.');
}read(file)#
Reads the content of a specified YAML file and parses it into a JavaScript object.
Parameters
Name | Type | Description |
|---|---|---|
|
| The full path to the |
Returns
Type | Description |
|---|---|
| The parsed content of the YAML file as a JavaScript object. |
Example
import { read, select } from '@blocklet/meta';
const blockletDir = '/path/to/your/blocklet';
try {
const metaFilePath = select(blockletDir);
const meta = read(metaFilePath);
console.log(`Blocklet Name: ${meta.name}`);
console.log(`Version: ${meta.version}`);
} catch (error) {
console.error('Failed to read metadata file:', error.message);
}update(file, meta, [options])#
Serializes a metadata object and writes it to a specified YAML file. It includes a fix option that cleans transient or runtime-only properties from the metadata before saving.
Parameters
Name | Type | Description |
|---|---|---|
|
| The path to the file where the metadata should be written. |
|
| The metadata object to serialize and write. |
|
| Optional. A configuration object. |
|
| Optional. If |
Returns
Type | Description |
|---|---|
| This function does not return a value. |
Example
import { read, select, update } from '@blocklet/meta';
const blockletDir = '/path/to/your/blocklet';
const metaFilePath = select(blockletDir);
// 1. Read the existing metadata
const meta = read(metaFilePath);
// 2. Modify a property
meta.description = 'An updated description for the blocklet.';
meta.version = '1.0.1';
// 3. Write the changes back to the file
// The `fix` option (default: true) will automatically clean the object.
update(metaFilePath, meta);
console.log(`Updated ${metaFilePath} with a new description and version.`);These file utilities form the building blocks for any tooling that needs to interact with blocklet.yml files. For a higher-level understanding of the metadata structure itself, refer to the Blocklet Specification.