@synet/fs
Version:
Robust, battle-tested filesystem abstraction for Node.js
368 lines (364 loc) • 12 kB
JavaScript
"use strict";
/**
* Async Filesystem Unit - Pure Asynchronous Operations
*
* This unit provides asynchronous filesystem operations with direct method access.
* No async/sync mixing, no runtime type checks, no zalgo.
*/
Object.defineProperty(exports, "__esModule", { value: true });
exports.AsyncFileSystem = void 0;
const unit_1 = require("@synet/unit");
const VERSION = "2.0.2";
/**
* Async Filesystem Unit - Pure asynchronous filesystem operations
*/
class AsyncFileSystem extends unit_1.Unit {
constructor(props) {
super(props);
}
/**
* Build consciousness trinity - creates living instances once
*/
build() {
const capabilities = unit_1.Capabilities.create(this.props.dna.id, {
readFile: (...args) => {
const params = args[0];
return this.readFile(params.path);
},
writeFile: (...args) => {
const params = args[0];
return this.writeFile(params.path, params.data);
},
exists: (...args) => {
const params = args[0];
return this.exists(params.path);
},
deleteFile: (...args) => {
const params = args[0];
return this.deleteFile(params.path);
},
readDir: (...args) => {
const params = args[0];
return this.readDir(params.path);
},
ensureDir: (...args) => {
const params = args[0];
return this.ensureDir(params.path);
},
deleteDir: (...args) => {
const params = args[0];
return this.deleteDir(params.path);
},
chmod: (...args) => {
const params = args[0];
return this.chmod(params.path, params.mode);
},
stat: (...args) => {
const params = args[0];
return this.stat(params.path);
}
});
const schema = unit_1.Schema.create(this.props.dna.id, {
readFile: {
name: 'readFile',
description: 'Read file content asynchronously',
parameters: {
type: 'object',
properties: {
path: { type: 'string', description: 'File path to read' }
},
required: ['path']
},
response: { type: 'string' }
},
writeFile: {
name: 'writeFile',
description: 'Write file content asynchronously',
parameters: {
type: 'object',
properties: {
path: { type: 'string', description: 'File path to write' },
data: { type: 'string', description: 'Data to write' }
},
required: ['path', 'data']
},
response: { type: 'void' }
},
exists: {
name: 'exists',
description: 'Check if file/directory exists asynchronously',
parameters: {
type: 'object',
properties: {
path: { type: 'string', description: 'Path to check' }
},
required: ['path']
},
response: { type: 'void' }
},
deleteFile: {
name: 'deleteFile',
description: 'Delete file asynchronously',
parameters: {
type: 'object',
properties: {
path: { type: 'string', description: 'File path to delete' }
},
required: ['path']
},
response: { type: 'void' }
},
readDir: {
name: 'readDir',
description: 'Read directory contents asynchronously',
parameters: {
type: 'object',
properties: {
path: { type: 'string', description: 'Directory path to read' }
},
required: ['path']
},
response: { type: 'array' }
},
ensureDir: {
name: 'ensureDir',
description: 'Ensure directory exists asynchronously',
parameters: {
type: 'object',
properties: {
path: { type: 'string', description: 'Directory path to ensure' }
},
required: ['path']
},
response: { type: 'void' }
},
deleteDir: {
name: 'deleteDir',
description: 'Delete directory asynchronously',
parameters: {
type: 'object',
properties: {
path: { type: 'string', description: 'Directory path to delete' }
},
required: ['path']
},
response: { type: 'void' }
},
chmod: {
name: 'chmod',
description: 'Set file permissions asynchronously',
parameters: {
type: 'object',
properties: {
path: { type: 'string', description: 'File path' },
mode: { type: 'number', description: 'Permission mode' }
},
required: ['path', 'mode']
},
response: { type: 'void' }
},
stat: {
name: 'stat',
description: 'Get file statistics asynchronously',
parameters: {
type: 'object',
properties: {
path: { type: 'string', description: 'File path to stat' }
},
required: ['path']
},
response: { type: 'object' }
}
});
const validator = unit_1.Validator.create({
unitId: this.props.dna.id,
capabilities,
schema,
strictMode: false
});
return { capabilities, schema, validator };
}
/**
* CREATE - Create a new async Filesystem Unit
*/
static create(config) {
const props = {
dna: (0, unit_1.createUnitSchema)({
id: "fs-async",
version: VERSION,
}),
backend: config.adapter,
config,
created: new Date(),
};
return new AsyncFileSystem(props);
}
/**
* Get capabilities consciousness - returns living instance
*/
capabilities() {
return this._unit.capabilities;
}
/**
* Get schema consciousness - returns living instance
*/
schema() {
return this._unit.schema;
}
/**
* Get validator consciousness - returns living instance
*/
validator() {
return this._unit.validator;
}
/**
* Normalize path for backend compatibility
*/
normalizePath(path) {
// Check if we're using a memory adapter by duck typing
if (this.props.backend.constructor.name === 'MemFileSystem') {
return path.startsWith("/") ? path : `/${path}`;
}
// Node, S3, GitHub and other adapters handle paths natively
return path;
}
// ==========================================
// NATIVE FILESYSTEM METHODS (ASYNC)
// ==========================================
/**
* Read file content asynchronously
*/
async readFile(path) {
const normalizedPath = this.normalizePath(path);
return await this.props.backend.readFile(normalizedPath);
}
/**
* Write file content asynchronously
*/
async writeFile(path, data) {
const normalizedPath = this.normalizePath(path);
await this.props.backend.writeFile(normalizedPath, data);
}
/**
* Check if file/directory exists asynchronously
*/
async exists(path) {
const normalizedPath = this.normalizePath(path);
return await this.props.backend.exists(normalizedPath);
}
/**
* Delete file asynchronously
*/
async deleteFile(path) {
const normalizedPath = this.normalizePath(path);
await this.props.backend.deleteFile(normalizedPath);
}
/**
* Read directory contents asynchronously
*/
async readDir(path) {
const normalizedPath = this.normalizePath(path);
return await this.props.backend.readDir(normalizedPath);
}
/**
* Ensure directory exists asynchronously
*/
async ensureDir(path) {
const normalizedPath = this.normalizePath(path);
await this.props.backend.ensureDir(normalizedPath);
}
/**
* Delete directory asynchronously
*/
async deleteDir(path) {
const normalizedPath = this.normalizePath(path);
await this.props.backend.deleteDir(normalizedPath);
}
/**
* Set file permissions asynchronously
*/
async chmod(path, mode) {
const normalizedPath = this.normalizePath(path);
await this.props.backend.chmod(normalizedPath, mode);
}
/**
* Get file statistics asynchronously
*/
async stat(path) {
const normalizedPath = this.normalizePath(path);
const result = await this.props.backend.stat?.(normalizedPath);
if (!result) {
throw new Error('stat method not available on this backend');
}
return result;
}
/**
* Clear directory contents asynchronously
*/
async clear(dirPath) {
if (!this.props.backend.clear) {
throw new Error('clear method not available on this backend');
}
const normalizedPath = this.normalizePath(dirPath);
await this.props.backend.clear(normalizedPath);
}
// ==========================================
// UNIT CAPABILITIES (for advanced features)
// ==========================================
/**
* TEACH - Provide filesystem capabilities to other units
*/
teach() {
return {
unitId: this.props.dna.id,
capabilities: this._unit.capabilities,
schema: this._unit.schema,
validator: this._unit.validator
};
}
whoami() {
return `AsyncFileSystem[${this.props.dna.id}]`;
}
help() {
console.log(`
AsyncFileSystem Unit - Asynchronous filesystem operations
Capabilities:
readFile - Read file contents
writeFile - Write file data
exists - Check if file exists
deleteFile - Delete file
readDir - List directory contents
ensureDir - Create directory if needed
deleteDir - Remove directory
chmod - Change file permissions
stat - Get file statistics
Usage:
const fs = AsyncFileSystem.create(config);
const data = await fs.readFile('/path/to/file');
When learned by other units:
await otherUnit.execute('${this.props.dna.id}.readFile', '/path/to/file');
`);
}
// ==========================================
// UNIT METADATA & UTILITIES
// ==========================================
/**
* Get operation statistics
*/
/**
* Get configuration
*/
getConfig() {
return { ...this.props.config };
}
/**
* Get direct access to the backend (escape hatch)
*/
getBackend() {
return this.props.backend;
}
isAsync() {
return true; // This unit is always async
}
}
exports.AsyncFileSystem = AsyncFileSystem;