marsrs-react-native-xlog 0.1.0-alpha.2 → 0.1.0-alpha.4

package/src/NativeXlog.ts

@@ -37,8 +37,32 @@ export interface Spec extends TurboModule {
    * holds. */
   getLevel(namePrefix: string): number;
 
-  /** `mars_xlog_flush_instance`. */
-  flush(namePrefix: string, sync: boolean): void;
+  /** `mars_xlog_request_flush_instance`: tells the writer thread it may take what is in
+   * the cache to the file, and returns at once — nothing waits, and nothing is
+   * in the file because this returned. */
+  requestFlush(namePrefix: string): void;
+
+  /** `mars_xlog_flush_now_instance`: the drain is the calling thread's, so the cache
+   * is in the log file, and the file's buffer is the OS's, when this returns. */
+  flushNow(namePrefix: string): void;
+
+  /** `flushNow` on a thread of the module's own, and a `Promise` settled when
+   * the drain is over: the one of the three that leaves the JS thread alone.
+   * A `Promise<void>` and not a `Promise` of a value — there is nothing to
+   * answer, only a drain to be over. */
+  flush(namePrefix: string): Promise<void>;
+
+  /** `mars_xlog_current_log_path_instance`: the directory this appender writes
+   * its files into, or `undefined` once it is closed. */
+  currentLogPath(namePrefix: string): string | undefined;
+
+  /** `mars_xlog_getfilepath_from_timespan_instance`: the day's files that are
+   * there — `0` is today, `1` is yesterday. */
+  logFiles(namePrefix: string, daysAgo: number): string[];
+
+  /** `mars_xlog_make_logfile_name_instance`: the day's names, whether or not the
+   * files are there yet. */
+  logFileNames(namePrefix: string, daysAgo: number): string[];
 
   /** `mars_xlog_set_level_instance`. */
   setLevel(namePrefix: string, level: number): void;
@@ -56,7 +80,8 @@ export interface Spec extends TurboModule {
   /** `mars_xlog_set_max_alive_duration_instance`. */
   setMaxAliveTime(namePrefix: string, seconds: number): void;
 
-  /** `mars_xlog_release_instance`: releases the appender `open` made. */
+  /** Releases the appender `open` made: by handle on iOS, by prefix on
+   * Android. */
   close(namePrefix: string): void;
 }
 

package/src/index.ts

@@ -37,7 +37,8 @@ export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
 /** `TAppenderMode`: whether a record reaches the file before the call returns. */
 export const AppenderMode = {
   /** The record goes into the memory-mapped cache and a writer thread takes it
-   * to the file — what the C++ opens with, and what `flush` drains. */
+   * to the file — what the C++ opens with, and what `flushNow()` and
+   * `await flush()` drain. */
   async: 0,
   /** The record is in the file before the call returns, at a write and a lock
    * per line. */
@@ -62,15 +63,16 @@ export type CompressMode = (typeof CompressMode)[keyof typeof CompressMode];
  * gives it: what an `Xlog` is opened with.
  *
  * Every field has the default the C++'s own `XLogConfig` carries, so the one an
- * app has to give is `logDir` — the appender answers
- * `MARS_XLOG_ERR_EMPTY_LOG_DIR` without it. */
+ * app has to give is `logDir` — the C ABI opens no appender
+ * without it. */
 export interface XlogConfig {
   /** Where the log files are written; created if it is missing, and the one
    * field with no default. */
   logDir: string;
   /** What every log file starts with (`marsrs_20260927.xlog`), and the name the
    * appender is known by — an app that writes through two of them gives them
-   * two. `xlog` when left out. */
+   * two. `xlog` when left out, when handed over empty, and when what was
+   * handed over is nothing but whitespace. */
   namePrefix?: string;
   /** The level the appender is opened at; `info` when left out. */
   level?: LogLevel;
@@ -89,9 +91,29 @@ export interface XlogConfig {
 }
 
 /** `XlogConfig.namePrefix` of the Kotlin and of the Swift: what an appender is
- * opened with when a caller gives none. */
+ * opened with when a caller gives none — and when it gives a blank one, which
+ * the two halves do not agree about: the Kotlin answers its own default for a
+ * prefix of nothing but whitespace, and the Swift opens that prefix as it is.
+ * Naming the default here is what keeps the `Xlog` an app holds and the
+ * appender the halves hold the same one, whichever half it is — a prefix of
+ * spaces that one half substituted and the other did not is an appender this
+ * `Xlog` cannot ask about afterwards. */
 const DEFAULT_NAME_PREFIX = 'xlog';
 
+/** The shortest lifetime of a file the appender takes, in seconds: one below it
+ * — `0` among them — is refused, and the appender keeps the lifetime it had.
+ * `MIN_LOG_ALIVE_TIME` of the Rust, which is the one place the number is
+ * written down. */
+const MIN_ALIVE_TIME_SECONDS = 86400;
+
+/** The prefix an appender opened with `config` is known by: `namePrefix`, or
+ * [DEFAULT_NAME_PREFIX] when it is missing or blank. What is handed to the two
+ * halves is this and not the string the caller gave, so the two of them agree
+ * on one name for one appender. */
+function namePrefixOf(config: XlogConfig): string {
+  return config.namePrefix?.trim() || DEFAULT_NAME_PREFIX;
+}
+
 /** The appender of every `namePrefix` `Xlog.open` has opened and `close` has
  * not closed, by the prefix: what makes two `Xlog.open`s of one prefix one
  * appender, which the native side already is — one module, one appender per
@@ -125,7 +147,7 @@ export class Xlog {
   private open = true;
 
   private constructor(config: XlogConfig) {
-    this.namePrefix = config.namePrefix ?? DEFAULT_NAME_PREFIX;
+    this.namePrefix = namePrefixOf(config);
     this.currentLevel = config.level ?? LogLevel.info;
     this.currentMode = config.mode ?? AppenderMode.async;
   }
@@ -138,16 +160,25 @@ export class Xlog {
    * second one over the first would be a handle nothing releases. So two calls
    * of one prefix are one `Xlog`, and `close` on it is `close` on both.
    *
+   * The native side is asked either way, and not only the first time: one
+   * appender per prefix is one for the whole app, so one the app closed
+   * through its own Kotlin or Swift is gone from under this map, and asking
+   * again is what opens it again.
+   *
    * Throws when the appender would not take the configuration — an empty
-   * `logDir` or `namePrefix`, or a directory it cannot write to. */
+   * `logDir`, or a directory it cannot write to. */
   static open(config: XlogConfig): Xlog {
-    const namePrefix = config.namePrefix ?? DEFAULT_NAME_PREFIX;
+    const namePrefix = namePrefixOf(config);
     const alreadyOpen = openAppenders.get(namePrefix);
-    if (alreadyOpen) {
+    // The appender of a prefix is one for the whole process, so one another
+    // part of the app closed is gone from under this map: the open is asked
+    // again instead of trusted, and what it answers is the appender that is
+    // there now — the same one when nothing closed it.
+    if (alreadyOpen && NativeXlog.open({ ...config, namePrefix })) {
       return alreadyOpen;
     }
     const xlog = new Xlog(config);
-    if (!NativeXlog.open(config)) {
+    if (!NativeXlog.open({ ...config, namePrefix })) {
       throw new Error(
         `marsrs-react-native-xlog: the appender of '${xlog.namePrefix}' refused ${config.logDir}`
       );
@@ -219,11 +250,21 @@ export class Xlog {
       return;
     }
     NativeXlog.setMaxFileSize(this.namePrefix, bytes);
-    this.currentMaxFileSize = bytes;
+    // Mirrored once it is a size the native side took, and not before: that
+    // side reads a `number` as an `unsigned long long`, and a negative one or
+    // a `NaN` is not one it hands over. `0` is a size and not an absence —
+    // "never split" — so it is mirrored like any other.
+    if (Number.isFinite(bytes) && bytes >= 0) {
+      this.currentMaxFileSize = bytes;
+    }
   }
 
-  /** How long a log file is written to before the appender opens the next one,
-   * in seconds; `0` is the C++'s own ten days. */
+  /** How many seconds a log file of this appender is kept before the sweep
+   * deletes it — and not how long one is written to, which is what the day's
+   * turn and [maxFileSizeBytes] decide: `0` is the lifetime an appender
+   * opened with none keeps, the C++'s own ten days, and one below a day is a
+   * lifetime the appender refuses, so what this answers is the one it has and
+   * not the last one it was asked for. */
   get maxAliveTimeSeconds(): number {
     return this.currentMaxAliveTime;
   }
@@ -233,7 +274,12 @@ export class Xlog {
       return;
     }
     NativeXlog.setMaxAliveTime(this.namePrefix, seconds);
-    this.currentMaxAliveTime = seconds;
+    // Mirrored once it is a lifetime the appender took, and not before: a day
+    // is the shortest one it takes, and `0` is below it, so a mirror that took
+    // the number would answer a lifetime no appender is writing under.
+    if (seconds >= MIN_ALIVE_TIME_SECONDS) {
+      this.currentMaxAliveTime = seconds;
+    }
   }
 
   /** Whether a record at `level` is written: the appender's own answer, and the
@@ -288,17 +334,94 @@ export class Xlog {
     this.log(LogLevel.fatal, tag, message);
   }
 
-  /** `mars_xlog_flush_instance`: takes what is in the cache to the file. `sync`
-   * waits for the write, which is what an app wants before it reads the file,
-   * uploads it, or lets the process go. */
-  flush(sync = false): void {
+  /** `mars_xlog_request_flush_instance`: tells the writer thread it may take what is in
+   * the cache to the file, and returns at once. Nothing waits, and nothing is
+   * in the file because this returned — a record still in the cache is in a file
+   * the kernel holds, so one whose process dies keeps it. What it is for is a
+   * drain an app wants soon and does not want to wait for; before the file is
+   * read, uploaded or left behind, it is `flushNow()` or `await flush()`
+   * that an app wants and not this. */
+  requestFlush(): void {
+    if (!this.open) {
+      return;
+    }
+    NativeXlog.requestFlush(this.namePrefix);
+  }
+
+  /** `mars_xlog_flush_now_instance`: the drain is the calling thread's, so the
+   * records are in the log file — handed to the OS, and not left in the file's
+   * own `FILE*` — when it returns, and what that costs is the time the drain
+   * takes, on the thread that asked for it. It answers no `Promise` and takes
+   * no `await`, which is the point of it: the line after the call is a line
+   * that runs after the drain, and there is nothing to get wrong in between. */
+  flushNow(): void {
+    if (!this.open) {
+      return;
+    }
+    NativeXlog.flushNow(this.namePrefix);
+  }
+
+  /** `flushNow()` off the JS thread: the same drain, on a thread of the
+   * module's own, and a `Promise` that is settled when it is over. The records
+   * are on disk when it resolves, and what waited for them is that thread and
+   * not the one the app runs JS on — the call to make before reading or
+   * uploading a log file whose drain is longer than the app can sit through. */
+  async flush(): Promise<void> {
     if (!this.open) {
       return;
     }
-    NativeXlog.flush(this.namePrefix, sync);
+    await NativeXlog.flush(this.namePrefix);
   }
 
-  /** `mars_xlog_release_instance`: closes the appender `Xlog.open` made.
+  /** `mars_xlog_current_log_path_instance`: the directory this appender writes
+   * its files into, or `undefined` once it is closed.
+   *
+   * A directory and not a file, because that is what the C++'s
+   * `GetCurrentLogPath` answers, and there is no "not yet" state: an open
+   * appender has a directory from the moment it is opened. What an app that
+   * uploads a whole day asks for is [`logFiles`]. */
+  get currentLogPath(): string | undefined {
+    if (!this.open) {
+      return undefined;
+    }
+    return NativeXlog.currentLogPath(this.namePrefix);
+  }
+
+  /** `mars_xlog_getfilepath_from_timespan_instance`: the log files of `daysAgo`
+   * days ago that are *there* — what an app that uploads yesterday's opens. `[]`
+   * when the directory holds none of that day's. `0` is today, `1` is yesterday,
+   * and so on.
+   *
+   * This is a day of files and not the directory they are in: what
+   * `currentLogPath` answers is that, and this is this appender's own prefix and
+   * directory. */
+  logFiles(daysAgo: number): string[] {
+    if (!this.open) {
+      return [];
+    }
+    return NativeXlog.logFiles(this.namePrefix, daysAgo);
+  }
+
+  /** `mars_xlog_make_logfile_name_instance`: the paths of the log files of
+   * `daysAgo` days ago whether or not they are *there yet* — the name an app
+   * that is about to write, or that is naming a file to someone else, asks for.
+   *
+   * A day's answer can be two where [`logFiles`] answers one, when a cache dir
+   * is given and the file is there. */
+  logFileNames(daysAgo: number): string[] {
+    if (!this.open) {
+      return [];
+    }
+    return NativeXlog.logFileNames(this.namePrefix, daysAgo);
+  }
+
+  /** Closes the appender `Xlog.open` made. `mars_xlog_release_instance_of` on
+   * iOS, which is given the handle beside the prefix — a release by prefix
+   * alone closes whichever appender the prefix answers at that moment — and
+   * `mars_xlog_release_instance` on Android, which releases the prefix and is
+   * asked once per `Xlog`, by whichever takes its handle out of the table
+   * first.
+   *
    * Nothing is closed twice: an `Xlog` that is already closed answers `false`
    * from `isOpen` and drops what it is asked to write — and an appender two
    * names hold is closed for both, because `Xlog.open` gave them one `Xlog`. */

package/android/.gradle/buildOutputCleanup/cache.properties

@@ -1,2 +0,0 @@
-#Mon Sep 28 14:47:25 CST 2026
-gradle.version=9.2.0