File Utilities

This module provides a set of low-level functions for interacting with blocklet.yml files on the filesystem. It includes utilities for locating, reading, and writing metadata files, as well as custom Joi extensions to streamline validation for file paths and DIDs.

blocklet.yml File Handlers#

These functions are the core building blocks for any tool that needs to programmatically read or modify a blocklet's metadata file.

select(dir, options?)#

The select function intelligently locates the correct blocklet.yml or blocklet.yaml file within a specified directory.

Parameters

dir
string
required
The absolute path to the directory where the blocklet metadata file is located.
options
object
Configuration options for the select function.
1 subfields

Returns

metaFilePath
string
The full, absolute path to the found metadata file, or an empty string if not found and `throwOnError` is false.

Example

Locating the metadata file

import { select } from '@blocklet/meta';

const blockletDir = '/path/to/your/blocklet';

try {
  const metaFile = select(blockletDir);
  console.log(`Found metadata file at: ${metaFile}`);
} catch (error) {
  console.error(error.message); // e.g., 'blocklet.yml not found...'
}

read(file)#

Once you have the file path, the read function parses the YAML content into a JavaScript object.

Parameters

file
string
required
The path to the blocklet.yml file to be read.

Returns

meta
object
The parsed content of the YAML file as a JavaScript object.

Example

Reading the metadata file

import { select, read } from '@blocklet/meta';

const metaFile = select('/path/to/your/blocklet');
const meta = read(metaFile);
console.log(`Blocklet name: ${meta.name}`);

update(file, meta, options?)#

The update function serializes a metadata object back into a YAML file. By default, it cleans the metadata by removing properties that are only relevant at runtime (e.g., path, stats, signatures) before writing.

Parameters

file
string
required
The path to the blocklet.yml file to be updated.
meta
TBlockletMeta
required
The metadata object to write to the file.
options
object
Configuration options for the update function.
1 subfields

Returns

This function does not return a value (void).

Example

Updating the metadata file

import { select, read, update } from '@blocklet/meta';

const metaFile = select('/path/to/your/blocklet');
let meta = read(metaFile);

// Modify the description
meta.description = 'An updated description for my blocklet.';

// Write the changes back to the file with cleanup
update(metaFile, meta);
console.log('blocklet.yml has been updated.');

list#

A simple constant array that contains the potential names for the blocklet metadata file, which select uses internally.

Example

import { list } from '@blocklet/meta';

console.log(list); // Outputs: ['blocklet.yml', 'blocklet.yaml']

Custom Joi Extensions#

These extensions integrate with the Joi validation library to provide custom validation types for common Blocklet-related data, such as file paths and DIDs.

fileExtension#

Provides a custom file() type for Joi schemas, enabling powerful file-system-aware validations.

Usage

First, extend a Joi instance with the fileExtension. Then, you can use the file() type and its rules in your schemas.

Joi Schema with fileExtension

import Joi from 'joi';
import path from 'path';
import { fileExtension } from '@blocklet/meta';

// Create a Joi instance extended with our custom types
const customJoi = Joi.extend(fileExtension);

const schema = customJoi.object({
  // Validates that 'logo.png' exists within the project directory
  logoPath: customJoi.file().exists({ baseDir: __dirname }),
});

const { error } = schema.validate({ logoPath: 'logo.png' });
if (error) {
  console.log(error.message); // e.g., 'file "logo.png" does not exist'
}

didExtension#

Provides a custom DID() type for Joi to validate ArcBlock Decentralized Identifiers.

Usage

Extend Joi with didExtension to add the DID() validation type.

Joi Schema with didExtension

import Joi from 'joi';
import { didExtension } from '@blocklet/meta';

const customJoi = Joi.extend(didExtension);

const schema = customJoi.object({
  author: customJoi.DID().required(),
});

// Example with an invalid DID
const { error } = schema.validate({ author: 'z123...invalid_did' });
if (error) {
  console.log(error.message); // 'did "z123...invalid_did" is not valid'
}

// Example with a valid DID
const { value } = schema.validate({ author: 'z8iZpbpJ4Yy2LzG1cqK9rC9pZ8r1Yq2Z3t4a' });
console.log(value); // { author: 'z8iZpbpJ4Yy2LzG1cqK9rC9pZ8r1Yq2Z3t4a' }

These file utilities form the foundation for many higher-level operations within the Blocklet ecosystem. For more advanced metadata handling, proceed to the Parsing & Validation documentation.

URL & Path Utilities
Miscellaneous Utilities