XyPrissXyPriss
Get Started

Watching & Streaming APIs

Version: XyPriss v6.1.0+
Branch: feature/advanced-watching

Overview

This document describes the high-performance file watching and streaming capabilities of the XyPriss System API. These features are powered by the native Rust engine (xsys) for maximum efficiency and reliability.

File Watching API

__sys__.$watch(path | path[], options)

Alias: __sys__.$wp(paths, options) (Watch Parallel)

Monitors one or more files or directories for system-level events (Created, Modified, Deleted, Renamed).

Parameters:

  • path (string | string[]): Single path or array of paths to monitor.
  • options (object):
    • duration (number): Watch duration in seconds (default: 60).

Parallel Example:

// Watch multiple project folders simultaneously
__sys__.$watch(["src", "tests", "docs"], { duration: 60 });

__sys__.$watchAndProcess(path, callback, options)

Alias: __sys__.$wap(path, callback, options)

Convenience utility that monitors a path and executes a logic callback after the cycle.

Example:

__sys__.$wap(
    ".",
    () => {
        console.log("Check complete.");
    },
    { duration: 10 }
);

__sys__.$watchContent(path | path[], options)

Alias: __sys__.$wc(path, options), __sys__.$wcp(paths, options)

NEW: Deep-monitoring sub-system that watches the actual content of one or more files in parallel.

Parameters:

  • path (string | string[]): Target file path(s).
  • options (object):
    • duration (number): Watch duration in seconds.
    • diff (boolean): If true, computes and displays granular additions/removals.

Example:

// Parallel content monitoring with diffing
__sys__.$wcp(["server.ts", "config.json"], { duration: 30, diff: true });

File Streaming API

__sys__.$stream(path, options)

Reads a file in chunks using buffered I/O. Use this for GB-scale files to avoid Node.js memory overflows.

Parameters:

  • path (string): Target file path.
  • options (object):
    • chunkSize (number): Size of each buffer in bytes (default: 8192).
    • hex (boolean): If true, returns hexadecimal representation.

Implementation Background

The implementation bypasses Node.js fs constraints by calling the xsys Rust binary:

  1. Watch: Uses the notify crate.
  2. Advanced Watcher: Implemented in advanced_watcher.rs for content diffing.
  3. Stream: Uses std::io::BufReader for optimized chunking.

Generated by Nehonix System Intelligence (NSI)

api/system/search-filterapi-reference