CKN Technology Data · IO Utilities

CKN Technology Data
File & Directory Classes

This page documents the File and Directory classes in @ckn-technology/data. They provide a small, opinionated wrapper over Node.js fs and path modules with logging and Array helpers integrated from @ckn-technology/core.

Import

The IO helpers live in @ckn-technology/data. You can import File and Directory either from the package root or the internal module that defines them.

Recommended

import { File, Directory } from "@ckn-technology/data";

Both classes internally use Node.js fs and path, the Log class from @ckn-technology/core, and extended Array helpers such as where, select, and union.

1. File Class – Overview

The File class wraps basic file system operations around a single file path:

  • Store and manipulate a file path (relative or absolute).
  • Read and write text content in UTF-8.
  • Check for existence of a file on disk.
  • Access path properties such as full path, directory, and file name.
  • Use a static helper to join path segments in a platform-safe way.
import { File } from "@ckn-technology/data";

const logFile = new File("./logs/app.log");

if (!logFile.isExist) {
    await logFile.writeText("Application started\n");
}

const currentContent = await logFile.readText();
console.log(currentContent);

1.2 Constructor & Path Properties

constructor(filePath)

Description
Creates a new File instance bound to the given file path.

  • Stores the path in a private #filePath field.
  • Initializes an internal logger: new Log("CKN", "STREAM", "FILE").

Signature

constructor(filePath: string)

Example

import { File } from "@ckn-technology/data";

const file = new File("./logs/app.log");

path (getter)

Description
Returns the raw file path as stored internally (may be relative).

Signature

get path(): string

Example

const file = new File("./data/users.json");
console.log(file.path); // "./data/users.json"

path (setter)

Description
Updates the underlying raw file path bound to this File instance.

Signature

set path(value: string)

Example

const file = new File("./data/users.json");
file.path = "./data/users-backup.json";

fullPath

Description
Returns the absolute path for the file using path.resolve.

Signature

get fullPath(): string

Example

const file = new File("./data/users.json");
console.log(file.fullPath); 
// e.g. "/home/app/data/users.json"

directory

Description
Returns a Directory instance representing the directory that contains this file.

  • Uses path.dirname(this.#filePath) to determine the folder.
  • Creates new Directory(...) from that path.

Signature

get directory(): Directory

Example

const file = new File("./data/users.json");
const dir = file.directory;

console.log(dir.path); // "./data"

name

Description
Returns the file name (with extension) using path.basename.

Signature

get name(): string

Example

const file = new File("./data/users.json");
console.log(file.name); // "users.json"

1.3 Reading, Writing & Existence

readText()

Description
Reads the file content as a UTF-8 string.

Although declared async, it uses fs.readFileSync internally and resolves immediately.

Signature

readText(): Promise<string>

Example

const file = new File("./config/app.json");

const text = await file.readText();
console.log(text);

isExist

Description
Checks if the file exists on disk.

Uses fs.existsSync(this.fullPath) under the hood.

Signature

get isExist(): boolean

Example

const file = new File("./data/users.json");

if (file.isExist) {
    console.log("File exists");
} else {
    console.log("File not found");
}

writeText(data)

Description
Writes a UTF-8 text string to the file. Creates the file if it does not exist.

Declared async but implemented with fs.writeFileSync.

Signature

writeText(data: string): Promise<void>

Example

const file = new File("./logs/app.log");

await file.writeText("Application started\n");

1.4 Static Utilities

File.join(...paths)

Description
Static utility that joins multiple path segments using path.join. Useful for building platform-independent file paths.

Signature

static join(...paths: string[]): string

Example

const full = File.join("logs", "2025", "app.log");
// e.g. "logs/2025/app.log" (platform-dependent)

2. Directory Class – Overview

The Directory class wraps basic operations around a folder path:

  • Represent a directory path (relative or absolute).
  • List files directly inside the directory (non-recursive).
  • Recursively list all files in the directory tree.
  • List subdirectories (as File instances).
  • Check whether the directory exists on disk.
import { Directory } from "@ckn-technology/data";

const dir = new Directory("./data");

if (dir.isExist) {
    console.log("Direct files:");
    dir.files.forEach(f => console.log("- ", f.name));

    console.log("All files (recursive):");
    dir.allFiles.forEach(f => console.log("- ", f.fullPath));
}

2.2 Constructor & Basic Properties

constructor(directoryPath)

Description
Creates a new Directory instance bound to the given path.

  • Stores the path in a private #directoryPath field.
  • Initializes a logger: new Log("CKN", "STREAM", "DIRECTORY").

Signature

constructor(directoryPath: string)

Example

import { Directory } from "@ckn-technology/data";

const dir = new Directory("./data");

path

Description
Returns the raw directory path (as originally passed in).

Signature

get path(): string

Example

const dir = new Directory("./data");
console.log(dir.path); // "./data"

fullPath

Description
Returns the absolute path for the directory using path.resolve.

Signature

get fullPath(): string

Example

const dir = new Directory("./data");
console.log(dir.fullPath); 
// e.g. "/home/app/data"

2.5 Listing Files & Directories

files

Description
Returns an array of File instances representing direct child files of the directory (non-recursive).

  • Uses fs.readdirSync(this.#directoryPath, { withFileTypes: true }).
  • Filters out directories using .where(p => !p.isDirectory()).
  • Maps file entries using .select(s => s.name) and new File(path.join(this.#directoryPath, f)).
  • If an error occurs, logs it via this.log.error(err) and returns an empty array.

Signature

get files(): File[]

Example

const dir = new Directory("./data");
const files = dir.files;

files.forEach(f => {
    console.log(f.name);
});

allFiles

Description
Returns an array of File instances for all files in the directory and subdirectories (recursive).

Internally calls a private helper #getAllFiles(currentPath).

Signature

get allFiles(): File[]

Example

const dir = new Directory("./data");
const all = dir.allFiles;

all.forEach(f => console.log(f.fullPath));

directories

Description
Returns an array of File instances representing the direct subdirectories of the directory.

Note: Each subdirectory is wrapped as a File instance, even though it refers to a directory path. This may be by design or subject to future refactor.

  • Calls fs.readdirSync(..., { withFileTypes: true }).
  • Filters entries with .where(p => p.isDirectory()).
  • Maps each to new File(path.join(this.#directoryPath, f)).

Signature

get directories(): File[]

Example

const dir = new Directory("./data");
const subDirsAsFiles = dir.directories;

subDirsAsFiles.forEach(f => console.log(f.path));

isExist

Description
Checks if the directory exists on disk.

Uses fs.existsSync(this.fullPath) internally.

Signature

get isExist(): boolean

Example

const dir = new Directory("./data");

if (!dir.isExist) {
    console.log("Directory not found");
}

2.9 Internal Helper (Private)

#getAllFiles(currentPath) (private)

Description
Recursively collects all files under currentPath. This is an implementation detail used by the allFiles getter and is not exposed as public API.

  • Reads directory entries with fs.readdirSync(currentPath, { withFileTypes: true }).
  • On error, logs via this.log.error(err).
  • Filters non-directory entries and creates File objects for them.
  • Filters directory entries and recursively calls #getAllFiles for each.
  • Merges results using Array .union(...) from @ckn-technology/core.

Signature

#getAllFiles(currentPath: string): File[]

Example usage is internal only (cannot be called from outside the Directory class).

3. Summary

The File and Directory classes in @ckn-technology/data provide a concise, logging-aware layer on top of Node.js filesystem APIs:

  • File – single-file abstraction with path helpers, existence checks, and simple UTF-8 text read/write operations plus a static join() helper.
  • Directory – folder abstraction with direct and recursive file listing, subdirectory enumeration, and existence checks.
  • Integration – leverages the Log utility and extended Array helpers (such as where, select, union) from @ckn-technology/core.

Together, these utilities standardize file and directory handling within the CKN ecosystem, making logging, error handling, and traversal behavior predictable and reusable across services and applications.