@synet/fs
Version:
Robust, battle-tested filesystem abstraction for Node.js
382 lines (378 loc) • 12.7 kB
JavaScript
"use strict";
/**
* Sync Filesystem Unit - Pure Synchronous Operations
*
* This unit provides synchronous filesystem operations with direct method access.
* Only includes backends that work well synchronously: node and memory.
* Cloud storage (GitHub, S3, GCS) should use the async filesystem unit.
*/
Object.defineProperty(exports, "__esModule", { value: true });
exports.FileSystem = void 0;
const unit_1 = require("@synet/unit");
const VERSION = "2.0.2";
/**
* Sync Filesystem Unit - Pure synchronous filesystem operations
*/
class FileSystem 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, {
readFileSync: (...args) => {
const params = args[0];
return this.readFileSync(params.path);
},
writeFileSync: (...args) => {
const params = args[0];
return this.writeFileSync(params.path, params.data);
},
existsSync: (...args) => {
const params = args[0];
return this.existsSync(params.path);
},
deleteFileSync: (...args) => {
const params = args[0];
return this.deleteFileSync(params.path);
},
readDirSync: (...args) => {
const params = args[0];
return this.readDirSync(params.path);
},
ensureDirSync: (...args) => {
const params = args[0];
return this.ensureDirSync(params.path);
},
deleteDirSync: (...args) => {
const params = args[0];
return this.deleteDirSync(params.path);
},
chmodSync: (...args) => {
const params = args[0];
return this.chmodSync(params.path, params.mode);
},
statSync: (...args) => {
const params = args[0];
return this.statSync(params.path);
},
clear: (...args) => {
const params = args[0];
return this.clear(params.dirPath);
}
});
const schema = unit_1.Schema.create(this.props.dna.id, {
readFileSync: {
name: 'readFileSync',
description: 'Read file content synchronously',
parameters: {
type: 'object',
properties: {
path: { type: 'string', description: 'File path to read' }
},
required: ['path']
},
response: { type: 'string' }
},
writeFileSync: {
name: 'writeFileSync',
description: 'Write file content synchronously',
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' }
},
existsSync: {
name: 'existsSync',
description: 'Check if file/directory exists synchronously',
parameters: {
type: 'object',
properties: {
path: { type: 'string', description: 'Path to check' }
},
required: ['path']
},
response: { type: 'void' }
},
deleteFileSync: {
name: 'deleteFileSync',
description: 'Delete file synchronously',
parameters: {
type: 'object',
properties: {
path: { type: 'string', description: 'File path to delete' }
},
required: ['path']
},
response: { type: 'void' }
},
readDirSync: {
name: 'readDirSync',
description: 'Read directory contents synchronously',
parameters: {
type: 'object',
properties: {
path: { type: 'string', description: 'Directory path to read' }
},
required: ['path']
},
response: { type: 'array' }
},
ensureDirSync: {
name: 'ensureDirSync',
description: 'Ensure directory exists synchronously',
parameters: {
type: 'object',
properties: {
path: { type: 'string', description: 'Directory path to ensure' }
},
required: ['path']
},
response: { type: 'void' }
},
deleteDirSync: {
name: 'deleteDirSync',
description: 'Delete directory synchronously',
parameters: {
type: 'object',
properties: {
path: { type: 'string', description: 'Directory path to delete' }
},
required: ['path']
},
response: { type: 'void' }
},
chmodSync: {
name: 'chmodSync',
description: 'Set file permissions synchronously',
parameters: {
type: 'object',
properties: {
path: { type: 'string', description: 'File path' },
mode: { type: 'number', description: 'Permission mode' }
},
required: ['path', 'mode']
},
response: { type: 'void' }
},
statSync: {
name: 'statSync',
description: 'Get file statistics synchronously',
parameters: {
type: 'object',
properties: {
path: { type: 'string', description: 'File path to stat' }
},
required: ['path']
},
response: { type: 'object' }
},
clear: {
name: 'clear',
description: 'Clear directory contents synchronously',
parameters: {
type: 'object',
properties: {
dirPath: { type: 'string', description: 'Directory path to clear' }
},
required: ['dirPath']
},
response: { type: 'void' }
}
});
const validator = unit_1.Validator.create({
unitId: this.props.dna.id,
capabilities,
schema,
strictMode: false
});
return { capabilities, schema, validator };
}
/**
* 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;
}
/**
* CREATE - Create a new sync Filesystem Unit
*/
static create(config) {
const props = {
dna: (0, unit_1.createUnitSchema)({
id: "fs",
version: VERSION,
description: "Sync filesystem unit, following node fs interface "
}),
backend: config.adapter,
config,
created: new Date(),
};
return new FileSystem(props);
}
// ==========================================
// NATIVE FILESYSTEM METHODS (with Sync suffix)
// ==========================================
/**
* Read file content synchronously
*/
readFileSync(path) {
const normalizedPath = this.normalizePath(path);
return this.props.backend.readFileSync(normalizedPath);
}
/**
* Write file content synchronously
*/
writeFileSync(path, data) {
const normalizedPath = this.normalizePath(path);
this.props.backend.writeFileSync(normalizedPath, data);
}
/**
* Check if file/directory exists synchronously
*/
existsSync(path) {
const normalizedPath = this.normalizePath(path);
return this.props.backend.existsSync(normalizedPath);
}
/**
* Delete file synchronously
*/
deleteFileSync(path) {
const normalizedPath = this.normalizePath(path);
this.props.backend.deleteFileSync(normalizedPath);
}
/**
* Read directory contents synchronously
*/
readDirSync(path) {
return this.props.backend.readDirSync(path);
}
/**
* Ensure directory exists synchronously
*/
ensureDirSync(path) {
const normalizedPath = this.normalizePath(path);
this.props.backend.ensureDirSync(normalizedPath);
}
/**
* Delete directory synchronously
*/
deleteDirSync(path) {
const normalizedPath = this.normalizePath(path);
this.props.backend.deleteDirSync(normalizedPath);
}
/**
* Set file permissions synchronously
*/
chmodSync(path, mode) {
const normalizedPath = this.normalizePath(path);
this.props.backend.chmodSync(normalizedPath, mode);
}
/**
* Get file statistics synchronously
*/
statSync(path) {
const normalizedPath = this.normalizePath(path);
const result = this.props.backend.statSync?.(normalizedPath);
if (!result) {
throw new Error('statSync method not available on this backend');
}
return result;
}
/**
* Clear directory contents synchronously
*/
clear(dirPath) {
const normalizedPath = this.normalizePath(dirPath);
if (!this.props.backend.clear) {
throw new Error('clear method not available on this backend');
}
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 `FileSystem[${this.props.dna.id}]`;
}
help() {
console.log(`
FileSystem Unit - Synchronous filesystem operations
Capabilities:
readFileSync - Read file contents
writeFileSync - Write file data
existsSync - Check if file exists
deleteFileSync - Delete file
readDirSync - List directory contents
ensureDirSync - Create directory if needed
deleteDirSync - Remove directory
chmodSync - Change file permissions
statSync - Get file statistics
Usage:
const fs = FileSystem.create(config);
const data = fs.readFileSync('/path/to/file');
When learned by other units:
otherUnit.execute('${this.props.dna.id}.readFileSync', '/path/to/file');
`);
}
// ==========================================
// UNIT METADATA & UTILITIES
// ==========================================
/**
* Get configuration
*/
getConfig() {
return { ...this.props.config };
}
/**
* Get direct access to the backend (escape hatch)
*/
getBackend() {
return this.props.backend;
}
isAsync() {
return false; // This unit is always sync
}
/**
* 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;
}
}
exports.FileSystem = FileSystem;