Method append

src/file-system.ts:36–86

* Appends contents to a file-path for persistance. File contents are * encrypted before being saved to disk. Reads happen via the in-memory * lookup of the internal map. Appends to the same path are serialized. * * @param path The filepath to persist contents to * @param newContent A

(
    path: string,
    newContent: string,
    shouldEncode: boolean,
    maxEntries?: number,
  )

   * @returns void
   */
  public async append(
    path: string,
    newContent: string,
    shouldEncode: boolean,
    maxEntries?: number,
  ): Promise<void> {
    if (
      maxEntries !== undefined &&
      (!Number.isInteger(maxEntries) || maxEntries < 1)
    ) {
      throw new Error(
        `maxEntries must be a positive integer when set, got "${maxEntries}"`,
      );
    }

    const prior = this.writeChains.get(path) ?? Promise.resolve();
    const task = prior.then(async () => {
      // Work on a copy — read() returns the live cached array, and the
      // cache must only reflect the new entry once the disk write has
      // succeeded, or a failed write leaves cache and file diverged.
      const contents = [...(await this.read(path, shouldEncode))];

      contents.push(newContent);
      if (maxEntries && contents.length > maxEntries) {
        contents.splice(0, contents.length - maxEntries);
      }

      const encoded = shouldEncode
        ? await encrypt(contents.join('\n'), this.currentAESKey)
        : contents.join('\n');

      await writeFile(path, encoded.toString());
      this.fsMap.set(path, contents);
      await this.recordMtime(path);
    });

    // Keep the chain alive past failures so one bad write doesn't wedge
    // every subsequent append to this path.
    const chain = task.catch(() => undefined);
    this.writeChains.set(path, chain);
    // Reclaim the entry once this chain settles — unless a newer append for
    // the same path has already replaced it — so the map doesn't retain one
    // resolved promise per distinct path for the life of the process.
    void chain.finally(() => {
      if (this.writeChains.get(path) === chain) {
        this.writeChains.delete(path);
      }
    });

    return task;
  }

  /**
   * Reads contents from the local map, if any exist and the file hasn't