@rabby-wallet/rabby-logger

Platform-agnostic Rabby log parsing and writing primitives.

This package provides:

• parsing for Rabby .log files and exported .zip archives
• @rabby-log/v1 line formatting
• a generic rolling zip writer
• a plain segment writer for hosts that want to defer zip work
• a generic logger core

It does not ship platform-specific storage or lifecycle adapters.

Install

npm install @rabby-wallet/rabby-logger

Parse logs

import {
  mergeParsedLogInputs,
  parseRabbyLogInputBytes,
} from "@rabby-wallet/rabby-logger";

const inputs = await Promise.all(
  files.map(async (file) =>
    parseRabbyLogInputBytes(file.name, await file.arrayBuffer()),
  ),
);

const dataset = mergeParsedLogInputs(inputs);
console.log(dataset.records[0]?.message);

Write logs

Most hosts should not implement a new writer from scratch.

Recommended path:

1. implement LoggingFileSystemAdapter
2. use the built-in RollingZipLogWriter
3. pass it to AppLogger

import {
  AppLogger,
  RollingZipLogWriter,
  type LoggingFileSystemAdapter,
} from "@rabby-wallet/rabby-logger";

const myFsAdapter: LoggingFileSystemAdapter = {
  mkdir: async (path) => {},
  readFile: async (path, encoding) => "...",
  writeFile: async (path, contents, encoding) => {},
  appendFile: async (path, contents, encoding) => {},
  moveFile: async (from, to) => {},
  listFiles: async (path) => [],
  unlink: async (path) => {},
};

const writer = new RollingZipLogWriter({
  fs: myFsAdapter,
  rootDir: "/applogs",
  archivePrefix: "rabby-mobile-logs",
});

const logger = new AppLogger({
  runtimeEnv: "production",
  platform: "ios",
  writer,
  shouldWriteToFile: () => true,
  shouldCaptureConsole: () => true,
});

logger.installConsoleCapture();
logger.info("app boot");
await logger.flush();
await logger.finalizeArchive();

Plain Segment Writer

For React Native hosts where zip compression is too expensive on the JS thread, use RollingTextLogWriter. It appends plain .log segment files on the hot path and only creates a zip archive during export/finalize.

Hosts can provide a native archive adapter so file reads and zip compression do not cross the JS/native bridge:

import { RollingTextLogWriter } from "@rabby-wallet/rabby-logger";

const writer = new RollingTextLogWriter({
  fs: myFsAdapter,
  rootDir: "/applogs",
  archivePrefix: "rabby-mobile-logs",
  archiveAdapter: {
    createZipArchive({ targetPath, entries, compressionLevel }) {
      return nativeLoggerZip.createZipArchive({
        targetPath,
        entries,
        compressionLevel,
      });
    },
  },
});

Bring Your Own Writer

If your host already owns archive layout, rotation, or native zip writing, implement AppLogWriter instead of LoggingFileSystemAdapter.

import { AppLogger, type AppLogWriter } from "@rabby-wallet/rabby-logger";

class NativeArchiveWriter implements AppLogWriter {
  async writeLine(line: string) {
    await nativeLogger.appendUtf8Line(line);
  }

  async flush() {
    await nativeLogger.flush();
  }

  async finalizeArchive() {
    return nativeLogger.finalizeZip();
  }

  getState() {
    return {
      rootDir: "/native/applogs",
      activeArchivePath: nativeLogger.currentArchivePath(),
    };
  }
}

const logger = new AppLogger({
  runtimeEnv: "production",
  platform: "android",
  writer: new NativeArchiveWriter(),
  shouldWriteToFile: () => true,
});

React Native Example

This is the same integration shape used by Rabby Mobile: react-native-fs provides the file operations, while RollingZipLogWriter keeps ownership of formatting, entry rotation, and archive finalization.

import { Platform } from "react-native";
import RNFS from "react-native-fs";
import {
  AppLogger,
  RollingZipLogWriter,
  type LoggingFileSystemAdapter,
} from "@rabby-wallet/rabby-logger";

const rnfsLoggingAdapter: LoggingFileSystemAdapter = {
  mkdir(path) {
    return RNFS.mkdir(path, { NSURLIsExcludedFromBackupKey: true });
  },
  readFile(path, encoding) {
    return RNFS.readFile(path, encoding);
  },
  writeFile(path, contents, encoding) {
    return RNFS.writeFile(path, contents, encoding);
  },
  appendFile(path, contents, encoding) {
    return RNFS.appendFile(path, contents, encoding);
  },
  moveFile(from, to) {
    return RNFS.moveFile(from, to);
  },
  async listFiles(path) {
    const entries = await RNFS.readDir(path);
    return entries.filter(item => item.isFile()).map(item => ({
      name: item.name,
      path: item.path,
      size: item.size,
      mtimeMs: item.mtime ? item.mtime.getTime() : undefined,
    }));
  },
  unlink(path) {
    return RNFS.unlink(path);
  },
};

const writer = new RollingZipLogWriter({
  fs: rnfsLoggingAdapter,
  rootDir: `${RNFS.DocumentDirectoryPath}/applogs`,
  archivePrefix: "rabby-mobile-logs",
});

export const logger = new AppLogger({
  runtimeEnv: "production",
  platform: Platform.OS,
  writer,
  shouldWriteToFile: () => true,
  shouldCaptureConsole: () => true,
});

Host responsibilities

The host application must provide:

• either a LoggingFileSystemAdapter for RollingZipLogWriter, or an AppLogWriter
• its own app lifecycle integration
• any platform-specific file sharing or export flow

Repository-only development notes live under packages/rabby-logger/docs/.