@unshared/fs 0.7.3 → 0.7.5

package/dist/loadObject.cjs

@@ -6,7 +6,7 @@ class FSObject extends node_events.EventEmitter {
    *
    * @param path The path or file descriptor of the file to load.
    * @param options Options for the watcher.
-   * @throws If the file is not a JSON object.
+   * @throws {Error} if the file cannot be accessed or parsed.
    */
   constructor(path, options = {}) {
     super(), this.path = path, this.options = options;

package/dist/loadObject.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"loadObject.cjs","sources":["../loadObject.ts"],"sourcesContent":["import type { Awaitable } from '@unshared/functions/awaitable'\nimport type { Reactive, ReactiveOptions } from '@unshared/reactivity/reactive'\nimport type { FSWatcher, PathLike, Stats, WatchOptions } from 'node:fs'\nimport { overwrite } from '@unshared/collection/overwrite'\nimport { awaitable } from '@unshared/functions/awaitable'\nimport { reactive } from '@unshared/reactivity/reactive'\nimport { EventEmitter } from 'node:events'\nimport { constants, watch } from 'node:fs'\nimport { access, mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises'\nimport { dirname } from 'node:path'\n\nexport interface FSObjectOptions<T extends object> extends ReactiveOptions<T>, WatchOptions {\n\n  /**\n   * If set to `true` and the file does not exist, the file will be created\n   * if it does not exist and the object will be initialized with an empty\n   * object.\n   *\n   * @default false\n   */\n  createIfNotExists?: boolean\n\n  /**\n   * If set to `true`, the file will be deleted when the instance is destroyed.\n   * Allowing you to create temporary files that will be deleted when the\n   * instance is garbage collected.\n   */\n  deleteOnDestroy?: boolean\n\n  /**\n   * If set to `true`, changes on the file will not be reflected in the object.\n   * You can use this to prevent the object from being updated when you are\n   * making changes to the file.\n   *\n   * @default false\n   */\n  ignoreFileChanges?: boolean\n\n  /**\n   * If set to `true`, changes on the object will be reflected in the file.\n   * You can set this to `false` if you want to make multiple changes to the\n   * object without triggering multiple file updates.\n   *\n   * @default false\n   */\n  ignoreObjectChanges?: boolean\n\n  /**\n   * The initial value of the object. If the file does not exist, the object\n   * will be initialized with this value.\n   *\n   * @default {}\n   */\n  initialValue?: T\n\n  /**\n   * The parser function to use when reading the file. If not set, the file\n   * will be parsed as JSON using the native `JSON.parse` function.\n   *\n   * @default JSON.parse\n   */\n  parse?: (json: string) => T\n\n  /**\n   * The stringifier function to use when writing the file. If not set, the\n   * object will be stringified as JSON using the native `JSON.stringify` function.\n   *\n   * @default JSON.stringify\n   */\n  serialize?: (object: T) => string\n}\n\nexport interface FSObjectEventMap<T extends object> {\n  commit: [T]\n  destroy: []\n  load: [T]\n  lock: []\n  unlock: []\n}\n\n// eslint-disable-next-line unicorn/prefer-event-target\nexport class FSObject<T extends object> extends EventEmitter<FSObjectEventMap<T>> {\n\n  /** Flag to signal the file is synchronized with the object. */\n  public isCommitting = false\n\n  /** Flag to signal the instance has been destroyed. */\n  public isDestroyed = false\n\n  /** Flag to signal the object is synchronized with the file. */\n  public isLoading = false\n\n  /** The current content of the file. */\n  public object: Reactive<T>\n\n  /** The current status of the file. */\n  public stats: Stats | undefined\n\n  /** A watcher that will update the object when the file changes. */\n  public watcher: FSWatcher | undefined\n\n  /**\n   * Load a JSON file and keep it synchronized with it's source file.\n   *\n   * @param path The path or file descriptor of the file to load.\n   * @param options Options for the watcher.\n   * @throws If the file is not a JSON object.\n   */\n  constructor(public path: PathLike, public options: FSObjectOptions<T> = {}) {\n    super()\n\n    // --- The callback that will be called when the object changes.\n    // --- This callback is wrapped in a debounce function to prevent\n    // --- multiple writes in a short period of time.\n    const callback = async() => {\n      if (this.isBusy) return\n      if (this.options.ignoreObjectChanges) return\n      await this.commit()\n    }\n\n    // --- Create the reactive object. Each time a nested property is\n    // --- changed, the callback will be called with the new object.\n    this.object = reactive(this.options.initialValue ?? {} as T, {\n      callbacks: [callback],\n      deep: true,\n      hooks: ['push', 'pop', 'shift', 'unshift', 'splice', 'sort', 'reverse'],\n      ...this.options,\n    })\n  }\n\n  /**\n   * Close the file and stop watching the file and object for changes.\n   * If the file has been created as a temporary file, it will be deleted.\n   *\n   * @returns A promise that resolves when the file has been destroyed.\n   */\n  async [Symbol.asyncDispose]() {\n    return this.destroy()\n  }\n\n  /**\n   * Create an awaitable instance of `FSObject` that resolves when the file\n   * is synchronized with the object and the object is synchronized with the file.\n   *\n   * This function is a shorthand for creating a new `FSObject` instance and\n   * calling the `access`, `load` and `watch` methods in sequence. This allows\n   * fast and easy access to the file and object in a single call.\n   *\n   * @param path The path or file descriptor of the file to load.\n   * @param options Options to pass to the `FSObject` constructor.\n   * @returns An awaitable instance of `FSObject`.\n   * @example\n   * const fsObject = FSObject.from('file.json')\n   * const object = await fsObject\n   *\n   * // Change the file and check the object.\n   * writeFileSync('file.json', '{\"foo\":\"bar\"}')\n   * await fsObject.untilLoaded\n   * object // => { foo: 'bar' }\n   *\n   * // Change the object and check the file.\n   * object.foo = 'baz'\n   * await fsObject.untilCommitted\n   * readFileSync('file.json', 'utf8') // => { \"foo\": \"baz\" }\n   */\n  static from<T extends object>(path: PathLike, options: FSObjectOptions<T> = {}): Awaitable<FSObject<T>, Reactive<T>> {\n    const fsObject = new FSObject<T>(path, options)\n    const createPromise = () => fsObject.load().then(() => fsObject.watch().object)\n    return awaitable(fsObject, createPromise)\n  }\n\n  /**\n   * Commit the current state of the object to the file. This function\n   * **will** write the object to the file and emit a `commit` event.\n   *\n   * @param writeObject The object to write to the file.\n   * @returns A promise that resolves when the file has been written.\n   */\n  public async commit(writeObject = this.object as T): Promise<void> {\n    this.isCommitting = true\n\n    // --- Stringify the object and write it to disk.\n    const { serialize = (object: unknown) => JSON.stringify(object, undefined, 2) } = this.options\n    const writeJson = serialize(writeObject)\n    const pathString = this.path.toString()\n    const pathDirectory = dirname(pathString)\n    await mkdir(pathDirectory, { recursive: true })\n    await writeFile(this.path, `${writeJson}\\n`, 'utf8')\n    overwrite(this.object, writeObject)\n    this.stats = await stat(this.path)\n\n    this.emit('commit', writeObject)\n    this.isCommitting = false\n  }\n\n  /**\n   * Close the file and stop watching the file and object for changes.\n   * If the file has been created as a temporary file, it will be deleted.\n   */\n  public async destroy(): Promise<void> {\n    this.isLoading = false\n    this.isCommitting = false\n    if (this.watcher) this.watcher.close()\n    if (this.options.deleteOnDestroy) await rm(this.path, { force: true })\n    this.watcher = undefined\n    this.isDestroyed = true\n    this.emit('destroy')\n  }\n\n  /**\n   * Load the file and update the object.\n   *\n   * @returns The loaded object.\n   */\n  public async load(): Promise<void> {\n    this.isLoading = true\n    this.isDestroyed = false\n\n    // --- If the file does not exist, and the `createIfNotExists` option is\n    // --- set to `true`, create the file and initialize the object with the\n    // --- `initialValue` option.\n    const accessError = await access(this.path, constants.F_OK | constants.R_OK).catch((error: Error) => error)\n    if (accessError && this.options.createIfNotExists) {\n      await this.commit()\n      this.isLoading = false\n      this.emit('load', this.object)\n      return\n    }\n\n    // --- If the file does not exist, throw an error.\n    if (accessError && !this.options.createIfNotExists) throw accessError\n\n    // --- Assert the path points to a file.\n    const newStats = await stat(this.path)\n    const newIsFile = newStats.isFile()\n    if (!newIsFile) throw new Error(`Expected ${this.path.toString()} to be a file`)\n\n    // --- If the file has not changed, return the current object.\n    if (this.object && this.stats && newStats.mtimeMs < this.stats.mtimeMs) return\n    this.stats = newStats\n\n    // --- Read and parse the file.\n    const { parse = JSON.parse } = this.options\n    const newJson = await readFile(this.path, 'utf8')\n    const newObject = parse(newJson) as T\n\n    // --- Assert JSON is an object.\n    if (typeof newObject !== 'object' || newObject === null)\n      throw new Error(`Expected ${this.path.toString()} to be a JSON object`)\n\n    // --- Update the object by overwriting it's properties.\n    overwrite(this.object, newObject)\n    this.isLoading = false\n    this.emit('load', newObject)\n  }\n\n  /**\n   * Start watching the file for changes and update the object if the content\n   * of the file changes.\n   *\n   * @returns The current instance for chaining.\n   * @example\n   * const object = new FSObject('file.json').watch()\n   *\n   * // Change the file and check the object.\n   * writeFileSync('file.json', '{\"foo\":\"bar\"}')\n   *\n   * // Wait until the object is updated.\n   * await object.untilLoaded\n   *\n   * // Check the object.\n   * expect(object.object).toStrictEqual({ foo: 'bar' })\n   */\n  public watch(): this {\n    if (this.watcher) return this\n\n    // --- Try to watch the file for changes. If an error occurs, the file\n    // --- is likely not accessible. In this case, just set the `isWatching`\n    // --- flag to `true` and retry watching the file when it becomes accessible.\n    this.watcher = watch(this.path, { persistent: false, ...this.options }, (event) => {\n      if (this.isBusy) return\n      if (this.options.ignoreFileChanges) return\n      if (event === 'change') void this.load()\n    })\n\n    // --- Return the instance for chaining.\n    return this\n  }\n\n  /**\n   * Flag to signal the instance is busy doing a commit or a load operation.\n   *\n   * @returns `true` if the instance is busy, `false` otherwise.\n   */\n  get isBusy() {\n    return this.isLoading || this.isCommitting || this.isDestroyed\n  }\n\n  /**\n   * A promise that resolves when the file is synchronized with the object.\n   *\n   * @returns A promise that resolves when the file is synchronized.\n   * @example\n   * const object = new FSObject('file.json')\n   * object.commit()\n   *\n   * // Wait until the file is synchronized.\n   * await object.untilCommitted\n   */\n  get untilCommitted(): Promise<void> {\n    if (!this.isCommitting) return Promise.resolve()\n    return new Promise<void>(resolve => this.prependOnceListener('commit', () => resolve()))\n  }\n\n  /**\n   * A promise that resolves when the object is destroyed.\n   *\n   * @returns A promise that resolves when the object is destroyed.\n   * @example\n   * const object = new FSObject('file.json')\n   * object.destroy()\n   *\n   * // Wait until the object is destroyed.\n   * await object.untilDestroyed\n   */\n  get untilDestroyed(): Promise<void> {\n    if (this.isDestroyed) return Promise.resolve()\n    return new Promise<void>(resolve => this.prependOnceListener('destroy', resolve))\n  }\n\n  /**\n   * A promise that resolves when the object is synchronized with the file.\n   *\n   * @returns A promise that resolves when the file is synchronized.\n   * @example\n   * const object = new FSObject('file.json')\n   * object.load()\n   *\n   * // Wait until the object is synchronized.\n   * await object.untilLoaded\n   */\n  get untilLoaded(): Promise<void> {\n    if (!this.isLoading) return Promise.resolve()\n    return new Promise<void>(resolve => this.prependOnceListener('load', () => resolve()))\n  }\n}\n\n/**\n * Create an awaitable instance of `FSObject` that resolves when the file\n * is synchronized with the object and the object is synchronized with the file.\n *\n * This function is a shorthand for creating a new `FSObject` instance and\n * calling the `access`, `load` and `watch` methods in sequence. This allows\n * fast and easy access to the file and object in a single call.\n *\n * @param path The path or file descriptor of the file to load.\n * @param options Options to pass to the `FSObject` constructor.\n * @returns An awaitable instance of `FSObject`.\n * @example\n * const fsObject = loadObject('file.json')\n * const object = await fsObject\n *\n * // Change the file and check the object.\n * writeFileSync('file.json', '{\"foo\":\"bar\"}')\n * await fsObject.untilLoaded\n * object // => { foo: 'bar' }\n *\n * // Change the object and check the file.\n * object.foo = 'baz'\n * await fsObject.untilCommitted\n * readFileSync('file.json', 'utf8') // => { \"foo\": \"baz\" }\n */\nexport function loadObject<T extends object>(path: PathLike, options: FSObjectOptions<T> = {}): Awaitable<FSObject<T>, Reactive<T>> {\n  return FSObject.from(path, options)\n}\n"],"names":["EventEmitter","reactive","awaitable","dirname","mkdir","writeFile","overwrite","stat","rm","access","constants","readFile","watch"],"mappings":"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"}
+{"version":3,"file":"loadObject.cjs","sources":["../loadObject.ts"],"sourcesContent":["import type { Awaitable } from '@unshared/functions/awaitable'\nimport type { Reactive, ReactiveOptions } from '@unshared/reactivity/reactive'\nimport type { FSWatcher, PathLike, Stats, WatchOptions } from 'node:fs'\nimport { overwrite } from '@unshared/collection/overwrite'\nimport { awaitable } from '@unshared/functions/awaitable'\nimport { reactive } from '@unshared/reactivity/reactive'\nimport { EventEmitter } from 'node:events'\nimport { constants, watch } from 'node:fs'\nimport { access, mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises'\nimport { dirname } from 'node:path'\n\nexport interface FSObjectOptions<T extends object> extends ReactiveOptions<T>, WatchOptions {\n\n  /**\n   * If set to `true` and the file does not exist, the file will be created\n   * if it does not exist and the object will be initialized with an empty\n   * object.\n   *\n   * @default false\n   */\n  createIfNotExists?: boolean\n\n  /**\n   * If set to `true`, the file will be deleted when the instance is destroyed.\n   * Allowing you to create temporary files that will be deleted when the\n   * instance is garbage collected.\n   */\n  deleteOnDestroy?: boolean\n\n  /**\n   * If set to `true`, changes on the file will not be reflected in the object.\n   * You can use this to prevent the object from being updated when you are\n   * making changes to the file.\n   *\n   * @default false\n   */\n  ignoreFileChanges?: boolean\n\n  /**\n   * If set to `true`, changes on the object will be reflected in the file.\n   * You can set this to `false` if you want to make multiple changes to the\n   * object without triggering multiple file updates.\n   *\n   * @default false\n   */\n  ignoreObjectChanges?: boolean\n\n  /**\n   * The initial value of the object. If the file does not exist, the object\n   * will be initialized with this value.\n   *\n   * @default {}\n   */\n  initialValue?: T\n\n  /**\n   * The parser function to use when reading the file. If not set, the file\n   * will be parsed as JSON using the native `JSON.parse` function.\n   *\n   * @default JSON.parse\n   */\n  parse?: (json: string) => T\n\n  /**\n   * The stringifier function to use when writing the file. If not set, the\n   * object will be stringified as JSON using the native `JSON.stringify` function.\n   *\n   * @default JSON.stringify\n   */\n  serialize?: (object: T) => string\n}\n\nexport interface FSObjectEventMap<T extends object> {\n  commit: [T]\n  destroy: []\n  load: [T]\n  lock: []\n  unlock: []\n}\n\n// eslint-disable-next-line unicorn/prefer-event-target\nexport class FSObject<T extends object> extends EventEmitter<FSObjectEventMap<T>> {\n\n  /** Flag to signal the file is synchronized with the object. */\n  public isCommitting = false\n\n  /** Flag to signal the instance has been destroyed. */\n  public isDestroyed = false\n\n  /** Flag to signal the object is synchronized with the file. */\n  public isLoading = false\n\n  /** The current content of the file. */\n  public object: Reactive<T>\n\n  /** The current status of the file. */\n  public stats: Stats | undefined\n\n  /** A watcher that will update the object when the file changes. */\n  public watcher: FSWatcher | undefined\n\n  /**\n   * Load a JSON file and keep it synchronized with it's source file.\n   *\n   * @param path The path or file descriptor of the file to load.\n   * @param options Options for the watcher.\n   * @throws {Error} if the file cannot be accessed or parsed.\n   */\n  constructor(public path: PathLike, public options: FSObjectOptions<T> = {}) {\n    super()\n\n    // --- The callback that will be called when the object changes.\n    // --- This callback is wrapped in a debounce function to prevent\n    // --- multiple writes in a short period of time.\n    const callback = async() => {\n      if (this.isBusy) return\n      if (this.options.ignoreObjectChanges) return\n      await this.commit()\n    }\n\n    // --- Create the reactive object. Each time a nested property is\n    // --- changed, the callback will be called with the new object.\n    this.object = reactive(this.options.initialValue ?? {} as T, {\n      callbacks: [callback],\n      deep: true,\n      hooks: ['push', 'pop', 'shift', 'unshift', 'splice', 'sort', 'reverse'],\n      ...this.options,\n    })\n  }\n\n  /**\n   * Close the file and stop watching the file and object for changes.\n   * If the file has been created as a temporary file, it will be deleted.\n   *\n   * @returns A promise that resolves when the file has been destroyed.\n   */\n  async [Symbol.asyncDispose]() {\n    return this.destroy()\n  }\n\n  /**\n   * Create an awaitable instance of `FSObject` that resolves when the file\n   * is synchronized with the object and the object is synchronized with the file.\n   *\n   * This function is a shorthand for creating a new `FSObject` instance and\n   * calling the `access`, `load` and `watch` methods in sequence. This allows\n   * fast and easy access to the file and object in a single call.\n   *\n   * @param path The path or file descriptor of the file to load.\n   * @param options Options to pass to the `FSObject` constructor.\n   * @returns An awaitable instance of `FSObject`.\n   * @example\n   * const fsObject = FSObject.from('file.json')\n   * const object = await fsObject\n   *\n   * // Change the file and check the object.\n   * writeFileSync('file.json', '{\"foo\":\"bar\"}')\n   * await fsObject.untilLoaded\n   * object // => { foo: 'bar' }\n   *\n   * // Change the object and check the file.\n   * object.foo = 'baz'\n   * await fsObject.untilCommitted\n   * readFileSync('file.json', 'utf8') // => { \"foo\": \"baz\" }\n   */\n  static from<T extends object>(path: PathLike, options: FSObjectOptions<T> = {}): Awaitable<FSObject<T>, Reactive<T>> {\n    const fsObject = new FSObject<T>(path, options)\n    const createPromise = () => fsObject.load().then(() => fsObject.watch().object)\n    return awaitable(fsObject, createPromise)\n  }\n\n  /**\n   * Commit the current state of the object to the file. This function\n   * **will** write the object to the file and emit a `commit` event.\n   *\n   * @param writeObject The object to write to the file.\n   * @returns A promise that resolves when the file has been written.\n   */\n  public async commit(writeObject = this.object as T): Promise<void> {\n    this.isCommitting = true\n\n    // --- Stringify the object and write it to disk.\n    const { serialize = (object: unknown) => JSON.stringify(object, undefined, 2) } = this.options\n    const writeJson = serialize(writeObject)\n    const pathString = this.path.toString()\n    const pathDirectory = dirname(pathString)\n    await mkdir(pathDirectory, { recursive: true })\n    await writeFile(this.path, `${writeJson}\\n`, 'utf8')\n    overwrite(this.object, writeObject)\n    this.stats = await stat(this.path)\n\n    this.emit('commit', writeObject)\n    this.isCommitting = false\n  }\n\n  /**\n   * Close the file and stop watching the file and object for changes.\n   * If the file has been created as a temporary file, it will be deleted.\n   */\n  public async destroy(): Promise<void> {\n    this.isLoading = false\n    this.isCommitting = false\n    if (this.watcher) this.watcher.close()\n    if (this.options.deleteOnDestroy) await rm(this.path, { force: true })\n    this.watcher = undefined\n    this.isDestroyed = true\n    this.emit('destroy')\n  }\n\n  /**\n   * Load the file and update the object.\n   *\n   * @returns The loaded object.\n   */\n  public async load(): Promise<void> {\n    this.isLoading = true\n    this.isDestroyed = false\n\n    // --- If the file does not exist, and the `createIfNotExists` option is\n    // --- set to `true`, create the file and initialize the object with the\n    // --- `initialValue` option.\n    const accessError = await access(this.path, constants.F_OK | constants.R_OK).catch((error: Error) => error)\n    if (accessError && this.options.createIfNotExists) {\n      await this.commit()\n      this.isLoading = false\n      this.emit('load', this.object)\n      return\n    }\n\n    // --- If the file does not exist, throw an error.\n    if (accessError && !this.options.createIfNotExists) throw accessError\n\n    // --- Assert the path points to a file.\n    const newStats = await stat(this.path)\n    const newIsFile = newStats.isFile()\n    if (!newIsFile) throw new Error(`Expected ${this.path.toString()} to be a file`)\n\n    // --- If the file has not changed, return the current object.\n    if (this.object && this.stats && newStats.mtimeMs < this.stats.mtimeMs) return\n    this.stats = newStats\n\n    // --- Read and parse the file.\n    const { parse = JSON.parse } = this.options\n    const newJson = await readFile(this.path, 'utf8')\n    const newObject = parse(newJson) as T\n\n    // --- Assert JSON is an object.\n    if (typeof newObject !== 'object' || newObject === null)\n      throw new Error(`Expected ${this.path.toString()} to be a JSON object`)\n\n    // --- Update the object by overwriting it's properties.\n    overwrite(this.object, newObject)\n    this.isLoading = false\n    this.emit('load', newObject)\n  }\n\n  /**\n   * Start watching the file for changes and update the object if the content\n   * of the file changes.\n   *\n   * @returns The current instance for chaining.\n   * @example\n   * const object = new FSObject('file.json').watch()\n   *\n   * // Change the file and check the object.\n   * writeFileSync('file.json', '{\"foo\":\"bar\"}')\n   *\n   * // Wait until the object is updated.\n   * await object.untilLoaded\n   *\n   * // Check the object.\n   * expect(object.object).toStrictEqual({ foo: 'bar' })\n   */\n  public watch(): this {\n    if (this.watcher) return this\n\n    // --- Try to watch the file for changes. If an error occurs, the file\n    // --- is likely not accessible. In this case, just set the `isWatching`\n    // --- flag to `true` and retry watching the file when it becomes accessible.\n    this.watcher = watch(this.path, { persistent: false, ...this.options }, (event) => {\n      if (this.isBusy) return\n      if (this.options.ignoreFileChanges) return\n      if (event === 'change') void this.load()\n    })\n\n    // --- Return the instance for chaining.\n    return this\n  }\n\n  /**\n   * Flag to signal the instance is busy doing a commit or a load operation.\n   *\n   * @returns `true` if the instance is busy, `false` otherwise.\n   */\n  get isBusy() {\n    return this.isLoading || this.isCommitting || this.isDestroyed\n  }\n\n  /**\n   * A promise that resolves when the file is synchronized with the object.\n   *\n   * @returns A promise that resolves when the file is synchronized.\n   * @example\n   * const object = new FSObject('file.json')\n   * object.commit()\n   *\n   * // Wait until the file is synchronized.\n   * await object.untilCommitted\n   */\n  get untilCommitted(): Promise<void> {\n    if (!this.isCommitting) return Promise.resolve()\n    return new Promise<void>(resolve => this.prependOnceListener('commit', () => resolve()))\n  }\n\n  /**\n   * A promise that resolves when the object is destroyed.\n   *\n   * @returns A promise that resolves when the object is destroyed.\n   * @example\n   * const object = new FSObject('file.json')\n   * object.destroy()\n   *\n   * // Wait until the object is destroyed.\n   * await object.untilDestroyed\n   */\n  get untilDestroyed(): Promise<void> {\n    if (this.isDestroyed) return Promise.resolve()\n    return new Promise<void>(resolve => this.prependOnceListener('destroy', resolve))\n  }\n\n  /**\n   * A promise that resolves when the object is synchronized with the file.\n   *\n   * @returns A promise that resolves when the file is synchronized.\n   * @example\n   * const object = new FSObject('file.json')\n   * object.load()\n   *\n   * // Wait until the object is synchronized.\n   * await object.untilLoaded\n   */\n  get untilLoaded(): Promise<void> {\n    if (!this.isLoading) return Promise.resolve()\n    return new Promise<void>(resolve => this.prependOnceListener('load', () => resolve()))\n  }\n}\n\n/**\n * Create an awaitable instance of `FSObject` that resolves when the file\n * is synchronized with the object and the object is synchronized with the file.\n *\n * This function is a shorthand for creating a new `FSObject` instance and\n * calling the `access`, `load` and `watch` methods in sequence. This allows\n * fast and easy access to the file and object in a single call.\n *\n * @param path The path or file descriptor of the file to load.\n * @param options Options to pass to the `FSObject` constructor.\n * @returns An awaitable instance of `FSObject`.\n * @example\n * const fsObject = loadObject('file.json')\n * const object = await fsObject\n *\n * // Change the file and check the object.\n * writeFileSync('file.json', '{\"foo\":\"bar\"}')\n * await fsObject.untilLoaded\n * object // => { foo: 'bar' }\n *\n * // Change the object and check the file.\n * object.foo = 'baz'\n * await fsObject.untilCommitted\n * readFileSync('file.json', 'utf8') // => { \"foo\": \"baz\" }\n */\nexport function loadObject<T extends object>(path: PathLike, options: FSObjectOptions<T> = {}): Awaitable<FSObject<T>, Reactive<T>> {\n  return FSObject.from(path, options)\n}\n"],"names":["EventEmitter","reactive","awaitable","dirname","mkdir","writeFile","overwrite","stat","rm","access","constants","readFile","watch"],"mappings":";;AAiFO,MAAM,iBAAmCA,YAAAA,aAAkC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EA2BhF,YAAmB,MAAuB,UAA8B,IAAI;AAC1E,UAAA,GADiB,KAAA,OAAA,MAAuB,KAAA,UAAA;AAMxC,UAAM,WAAW,YAAW;AACtB,WAAK,UACL,KAAK,QAAQ,uBACjB,MAAM,KAAK,OAAA;AAAA,IACb;AAIA,SAAK,SAASC,SAAAA,SAAS,KAAK,QAAQ,gBAAgB,IAAS;AAAA,MAC3D,WAAW,CAAC,QAAQ;AAAA,MACpB,MAAM;AAAA,MACN,OAAO,CAAC,QAAQ,OAAO,SAAS,WAAW,UAAU,QAAQ,SAAS;AAAA,MACtE,GAAG,KAAK;AAAA,IAAA,CACT;AAAA,EACH;AAAA;AAAA,EA5CO,eAAe;AAAA;AAAA,EAGf,cAAc;AAAA;AAAA,EAGd,YAAY;AAAA;AAAA,EAGZ;AAAA;AAAA,EAGA;AAAA;AAAA,EAGA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAqCP,OAAO,OAAO,YAAY,IAAI;AAC5B,WAAO,KAAK,QAAA;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EA2BA,OAAO,KAAuB,MAAgB,UAA8B,IAAyC;AACnH,UAAM,WAAW,IAAI,SAAY,MAAM,OAAO;AAE9C,WAAOC,oBAAU,UADK,MAAM,SAAS,KAAA,EAAO,KAAK,MAAM,SAAS,MAAA,EAAQ,MAAM,CACtC;AAAA,EAC1C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,MAAa,OAAO,cAAc,KAAK,QAA4B;AACjE,SAAK,eAAe;AAGpB,UAAM,EAAE,YAAY,CAAC,WAAoB,KAAK,UAAU,QAAQ,QAAW,CAAC,EAAA,IAAM,KAAK,SACjF,YAAY,UAAU,WAAW,GACjC,aAAa,KAAK,KAAK,SAAA,GACvB,gBAAgBC,UAAAA,QAAQ,UAAU;AACxC,UAAMC,eAAM,eAAe,EAAE,WAAW,GAAA,CAAM,GAC9C,MAAMC,mBAAU,KAAK,MAAM,GAAG,SAAS;AAAA,GAAM,MAAM,GACnDC,UAAAA,UAAU,KAAK,QAAQ,WAAW,GAClC,KAAK,QAAQ,MAAMC,SAAAA,KAAK,KAAK,IAAI,GAEjC,KAAK,KAAK,UAAU,WAAW,GAC/B,KAAK,eAAe;AAAA,EACtB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAa,UAAyB;AACpC,SAAK,YAAY,IACjB,KAAK,eAAe,IAChB,KAAK,WAAS,KAAK,QAAQ,MAAA,GAC3B,KAAK,QAAQ,mBAAiB,MAAMC,SAAAA,GAAG,KAAK,MAAM,EAAE,OAAO,GAAA,CAAM,GACrE,KAAK,UAAU,QACf,KAAK,cAAc,IACnB,KAAK,KAAK,SAAS;AAAA,EACrB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAa,OAAsB;AACjC,SAAK,YAAY,IACjB,KAAK,cAAc;AAKnB,UAAM,cAAc,MAAMC,SAAAA,OAAO,KAAK,MAAMC,QAAAA,UAAU,OAAOA,QAAAA,UAAU,IAAI,EAAE,MAAM,CAAC,UAAiB,KAAK;AAC1G,QAAI,eAAe,KAAK,QAAQ,mBAAmB;AACjD,YAAM,KAAK,UACX,KAAK,YAAY,IACjB,KAAK,KAAK,QAAQ,KAAK,MAAM;AAC7B;AAAA,IACF;AAGA,QAAI,eAAe,CAAC,KAAK,QAAQ,kBAAmB,OAAM;AAG1D,UAAM,WAAW,MAAMH,cAAK,KAAK,IAAI;AAErC,QAAI,CADc,SAAS,OAAA,EACX,OAAM,IAAI,MAAM,YAAY,KAAK,KAAK,SAAA,CAAU,eAAe;AAG/E,QAAI,KAAK,UAAU,KAAK,SAAS,SAAS,UAAU,KAAK,MAAM,QAAS;AACxE,SAAK,QAAQ;AAGb,UAAM,EAAE,QAAQ,KAAK,MAAA,IAAU,KAAK,SAC9B,UAAU,MAAMI,SAAAA,SAAS,KAAK,MAAM,MAAM,GAC1C,YAAY,MAAM,OAAO;AAG/B,QAAI,OAAO,aAAc,YAAY,cAAc;AACjD,YAAM,IAAI,MAAM,YAAY,KAAK,KAAK,SAAA,CAAU,sBAAsB;AAGxEL,cAAAA,UAAU,KAAK,QAAQ,SAAS,GAChC,KAAK,YAAY,IACjB,KAAK,KAAK,QAAQ,SAAS;AAAA,EAC7B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAmBO,QAAc;AACnB,WAAI,KAAK,UAAgB,QAKzB,KAAK,UAAUM,QAAAA,MAAM,KAAK,MAAM,EAAE,YAAY,IAAO,GAAG,KAAK,QAAA,GAAW,CAAC,UAAU;AAC7E,WAAK,UACL,KAAK,QAAQ,qBACb,UAAU,YAAe,KAAK,KAAA;AAAA,IACpC,CAAC,GAGM;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,IAAI,SAAS;AACX,WAAO,KAAK,aAAa,KAAK,gBAAgB,KAAK;AAAA,EACrD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAaA,IAAI,iBAAgC;AAClC,WAAK,KAAK,eACH,IAAI,QAAc,aAAW,KAAK,oBAAoB,UAAU,MAAM,QAAA,CAAS,CAAC,IADxD,QAAQ,QAAA;AAAA,EAEzC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAaA,IAAI,iBAAgC;AAClC,WAAI,KAAK,cAAoB,QAAQ,QAAA,IAC9B,IAAI,QAAc,CAAA,YAAW,KAAK,oBAAoB,WAAW,OAAO,CAAC;AAAA,EAClF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAaA,IAAI,cAA6B;AAC/B,WAAK,KAAK,YACH,IAAI,QAAc,aAAW,KAAK,oBAAoB,QAAQ,MAAM,QAAA,CAAS,CAAC,IADzD,QAAQ,QAAA;AAAA,EAEtC;AACF;AA2BO,SAAS,WAA6B,MAAgB,UAA8B,IAAyC;AAClI,SAAO,SAAS,KAAK,MAAM,OAAO;AACpC;;;"}

package/dist/loadObject.d.ts

@@ -83,7 +83,7 @@ declare class FSObject<T extends object> extends EventEmitter<FSObjectEventMap<T
      *
      * @param path The path or file descriptor of the file to load.
      * @param options Options for the watcher.
-     * @throws If the file is not a JSON object.
+     * @throws {Error} if the file cannot be accessed or parsed.
      */
     constructor(path: PathLike, options?: FSObjectOptions<T>);
     /**

package/dist/loadObject.js

@@ -11,7 +11,7 @@ class FSObject extends EventEmitter {
    *
    * @param path The path or file descriptor of the file to load.
    * @param options Options for the watcher.
-   * @throws If the file is not a JSON object.
+   * @throws {Error} if the file cannot be accessed or parsed.
    */
   constructor(path, options = {}) {
     super(), this.path = path, this.options = options;

package/dist/loadObject.js.map

@@ -1 +1 @@
-{"version":3,"file":"loadObject.js","sources":["../loadObject.ts"],"sourcesContent":["import type { Awaitable } from '@unshared/functions/awaitable'\nimport type { Reactive, ReactiveOptions } from '@unshared/reactivity/reactive'\nimport type { FSWatcher, PathLike, Stats, WatchOptions } from 'node:fs'\nimport { overwrite } from '@unshared/collection/overwrite'\nimport { awaitable } from '@unshared/functions/awaitable'\nimport { reactive } from '@unshared/reactivity/reactive'\nimport { EventEmitter } from 'node:events'\nimport { constants, watch } from 'node:fs'\nimport { access, mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises'\nimport { dirname } from 'node:path'\n\nexport interface FSObjectOptions<T extends object> extends ReactiveOptions<T>, WatchOptions {\n\n  /**\n   * If set to `true` and the file does not exist, the file will be created\n   * if it does not exist and the object will be initialized with an empty\n   * object.\n   *\n   * @default false\n   */\n  createIfNotExists?: boolean\n\n  /**\n   * If set to `true`, the file will be deleted when the instance is destroyed.\n   * Allowing you to create temporary files that will be deleted when the\n   * instance is garbage collected.\n   */\n  deleteOnDestroy?: boolean\n\n  /**\n   * If set to `true`, changes on the file will not be reflected in the object.\n   * You can use this to prevent the object from being updated when you are\n   * making changes to the file.\n   *\n   * @default false\n   */\n  ignoreFileChanges?: boolean\n\n  /**\n   * If set to `true`, changes on the object will be reflected in the file.\n   * You can set this to `false` if you want to make multiple changes to the\n   * object without triggering multiple file updates.\n   *\n   * @default false\n   */\n  ignoreObjectChanges?: boolean\n\n  /**\n   * The initial value of the object. If the file does not exist, the object\n   * will be initialized with this value.\n   *\n   * @default {}\n   */\n  initialValue?: T\n\n  /**\n   * The parser function to use when reading the file. If not set, the file\n   * will be parsed as JSON using the native `JSON.parse` function.\n   *\n   * @default JSON.parse\n   */\n  parse?: (json: string) => T\n\n  /**\n   * The stringifier function to use when writing the file. If not set, the\n   * object will be stringified as JSON using the native `JSON.stringify` function.\n   *\n   * @default JSON.stringify\n   */\n  serialize?: (object: T) => string\n}\n\nexport interface FSObjectEventMap<T extends object> {\n  commit: [T]\n  destroy: []\n  load: [T]\n  lock: []\n  unlock: []\n}\n\n// eslint-disable-next-line unicorn/prefer-event-target\nexport class FSObject<T extends object> extends EventEmitter<FSObjectEventMap<T>> {\n\n  /** Flag to signal the file is synchronized with the object. */\n  public isCommitting = false\n\n  /** Flag to signal the instance has been destroyed. */\n  public isDestroyed = false\n\n  /** Flag to signal the object is synchronized with the file. */\n  public isLoading = false\n\n  /** The current content of the file. */\n  public object: Reactive<T>\n\n  /** The current status of the file. */\n  public stats: Stats | undefined\n\n  /** A watcher that will update the object when the file changes. */\n  public watcher: FSWatcher | undefined\n\n  /**\n   * Load a JSON file and keep it synchronized with it's source file.\n   *\n   * @param path The path or file descriptor of the file to load.\n   * @param options Options for the watcher.\n   * @throws If the file is not a JSON object.\n   */\n  constructor(public path: PathLike, public options: FSObjectOptions<T> = {}) {\n    super()\n\n    // --- The callback that will be called when the object changes.\n    // --- This callback is wrapped in a debounce function to prevent\n    // --- multiple writes in a short period of time.\n    const callback = async() => {\n      if (this.isBusy) return\n      if (this.options.ignoreObjectChanges) return\n      await this.commit()\n    }\n\n    // --- Create the reactive object. Each time a nested property is\n    // --- changed, the callback will be called with the new object.\n    this.object = reactive(this.options.initialValue ?? {} as T, {\n      callbacks: [callback],\n      deep: true,\n      hooks: ['push', 'pop', 'shift', 'unshift', 'splice', 'sort', 'reverse'],\n      ...this.options,\n    })\n  }\n\n  /**\n   * Close the file and stop watching the file and object for changes.\n   * If the file has been created as a temporary file, it will be deleted.\n   *\n   * @returns A promise that resolves when the file has been destroyed.\n   */\n  async [Symbol.asyncDispose]() {\n    return this.destroy()\n  }\n\n  /**\n   * Create an awaitable instance of `FSObject` that resolves when the file\n   * is synchronized with the object and the object is synchronized with the file.\n   *\n   * This function is a shorthand for creating a new `FSObject` instance and\n   * calling the `access`, `load` and `watch` methods in sequence. This allows\n   * fast and easy access to the file and object in a single call.\n   *\n   * @param path The path or file descriptor of the file to load.\n   * @param options Options to pass to the `FSObject` constructor.\n   * @returns An awaitable instance of `FSObject`.\n   * @example\n   * const fsObject = FSObject.from('file.json')\n   * const object = await fsObject\n   *\n   * // Change the file and check the object.\n   * writeFileSync('file.json', '{\"foo\":\"bar\"}')\n   * await fsObject.untilLoaded\n   * object // => { foo: 'bar' }\n   *\n   * // Change the object and check the file.\n   * object.foo = 'baz'\n   * await fsObject.untilCommitted\n   * readFileSync('file.json', 'utf8') // => { \"foo\": \"baz\" }\n   */\n  static from<T extends object>(path: PathLike, options: FSObjectOptions<T> = {}): Awaitable<FSObject<T>, Reactive<T>> {\n    const fsObject = new FSObject<T>(path, options)\n    const createPromise = () => fsObject.load().then(() => fsObject.watch().object)\n    return awaitable(fsObject, createPromise)\n  }\n\n  /**\n   * Commit the current state of the object to the file. This function\n   * **will** write the object to the file and emit a `commit` event.\n   *\n   * @param writeObject The object to write to the file.\n   * @returns A promise that resolves when the file has been written.\n   */\n  public async commit(writeObject = this.object as T): Promise<void> {\n    this.isCommitting = true\n\n    // --- Stringify the object and write it to disk.\n    const { serialize = (object: unknown) => JSON.stringify(object, undefined, 2) } = this.options\n    const writeJson = serialize(writeObject)\n    const pathString = this.path.toString()\n    const pathDirectory = dirname(pathString)\n    await mkdir(pathDirectory, { recursive: true })\n    await writeFile(this.path, `${writeJson}\\n`, 'utf8')\n    overwrite(this.object, writeObject)\n    this.stats = await stat(this.path)\n\n    this.emit('commit', writeObject)\n    this.isCommitting = false\n  }\n\n  /**\n   * Close the file and stop watching the file and object for changes.\n   * If the file has been created as a temporary file, it will be deleted.\n   */\n  public async destroy(): Promise<void> {\n    this.isLoading = false\n    this.isCommitting = false\n    if (this.watcher) this.watcher.close()\n    if (this.options.deleteOnDestroy) await rm(this.path, { force: true })\n    this.watcher = undefined\n    this.isDestroyed = true\n    this.emit('destroy')\n  }\n\n  /**\n   * Load the file and update the object.\n   *\n   * @returns The loaded object.\n   */\n  public async load(): Promise<void> {\n    this.isLoading = true\n    this.isDestroyed = false\n\n    // --- If the file does not exist, and the `createIfNotExists` option is\n    // --- set to `true`, create the file and initialize the object with the\n    // --- `initialValue` option.\n    const accessError = await access(this.path, constants.F_OK | constants.R_OK).catch((error: Error) => error)\n    if (accessError && this.options.createIfNotExists) {\n      await this.commit()\n      this.isLoading = false\n      this.emit('load', this.object)\n      return\n    }\n\n    // --- If the file does not exist, throw an error.\n    if (accessError && !this.options.createIfNotExists) throw accessError\n\n    // --- Assert the path points to a file.\n    const newStats = await stat(this.path)\n    const newIsFile = newStats.isFile()\n    if (!newIsFile) throw new Error(`Expected ${this.path.toString()} to be a file`)\n\n    // --- If the file has not changed, return the current object.\n    if (this.object && this.stats && newStats.mtimeMs < this.stats.mtimeMs) return\n    this.stats = newStats\n\n    // --- Read and parse the file.\n    const { parse = JSON.parse } = this.options\n    const newJson = await readFile(this.path, 'utf8')\n    const newObject = parse(newJson) as T\n\n    // --- Assert JSON is an object.\n    if (typeof newObject !== 'object' || newObject === null)\n      throw new Error(`Expected ${this.path.toString()} to be a JSON object`)\n\n    // --- Update the object by overwriting it's properties.\n    overwrite(this.object, newObject)\n    this.isLoading = false\n    this.emit('load', newObject)\n  }\n\n  /**\n   * Start watching the file for changes and update the object if the content\n   * of the file changes.\n   *\n   * @returns The current instance for chaining.\n   * @example\n   * const object = new FSObject('file.json').watch()\n   *\n   * // Change the file and check the object.\n   * writeFileSync('file.json', '{\"foo\":\"bar\"}')\n   *\n   * // Wait until the object is updated.\n   * await object.untilLoaded\n   *\n   * // Check the object.\n   * expect(object.object).toStrictEqual({ foo: 'bar' })\n   */\n  public watch(): this {\n    if (this.watcher) return this\n\n    // --- Try to watch the file for changes. If an error occurs, the file\n    // --- is likely not accessible. In this case, just set the `isWatching`\n    // --- flag to `true` and retry watching the file when it becomes accessible.\n    this.watcher = watch(this.path, { persistent: false, ...this.options }, (event) => {\n      if (this.isBusy) return\n      if (this.options.ignoreFileChanges) return\n      if (event === 'change') void this.load()\n    })\n\n    // --- Return the instance for chaining.\n    return this\n  }\n\n  /**\n   * Flag to signal the instance is busy doing a commit or a load operation.\n   *\n   * @returns `true` if the instance is busy, `false` otherwise.\n   */\n  get isBusy() {\n    return this.isLoading || this.isCommitting || this.isDestroyed\n  }\n\n  /**\n   * A promise that resolves when the file is synchronized with the object.\n   *\n   * @returns A promise that resolves when the file is synchronized.\n   * @example\n   * const object = new FSObject('file.json')\n   * object.commit()\n   *\n   * // Wait until the file is synchronized.\n   * await object.untilCommitted\n   */\n  get untilCommitted(): Promise<void> {\n    if (!this.isCommitting) return Promise.resolve()\n    return new Promise<void>(resolve => this.prependOnceListener('commit', () => resolve()))\n  }\n\n  /**\n   * A promise that resolves when the object is destroyed.\n   *\n   * @returns A promise that resolves when the object is destroyed.\n   * @example\n   * const object = new FSObject('file.json')\n   * object.destroy()\n   *\n   * // Wait until the object is destroyed.\n   * await object.untilDestroyed\n   */\n  get untilDestroyed(): Promise<void> {\n    if (this.isDestroyed) return Promise.resolve()\n    return new Promise<void>(resolve => this.prependOnceListener('destroy', resolve))\n  }\n\n  /**\n   * A promise that resolves when the object is synchronized with the file.\n   *\n   * @returns A promise that resolves when the file is synchronized.\n   * @example\n   * const object = new FSObject('file.json')\n   * object.load()\n   *\n   * // Wait until the object is synchronized.\n   * await object.untilLoaded\n   */\n  get untilLoaded(): Promise<void> {\n    if (!this.isLoading) return Promise.resolve()\n    return new Promise<void>(resolve => this.prependOnceListener('load', () => resolve()))\n  }\n}\n\n/**\n * Create an awaitable instance of `FSObject` that resolves when the file\n * is synchronized with the object and the object is synchronized with the file.\n *\n * This function is a shorthand for creating a new `FSObject` instance and\n * calling the `access`, `load` and `watch` methods in sequence. This allows\n * fast and easy access to the file and object in a single call.\n *\n * @param path The path or file descriptor of the file to load.\n * @param options Options to pass to the `FSObject` constructor.\n * @returns An awaitable instance of `FSObject`.\n * @example\n * const fsObject = loadObject('file.json')\n * const object = await fsObject\n *\n * // Change the file and check the object.\n * writeFileSync('file.json', '{\"foo\":\"bar\"}')\n * await fsObject.untilLoaded\n * object // => { foo: 'bar' }\n *\n * // Change the object and check the file.\n * object.foo = 'baz'\n * await fsObject.untilCommitted\n * readFileSync('file.json', 'utf8') // => { \"foo\": \"baz\" }\n */\nexport function loadObject<T extends object>(path: PathLike, options: FSObjectOptions<T> = {}): Awaitable<FSObject<T>, Reactive<T>> {\n  return FSObject.from(path, options)\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"loadObject.js","sources":["../loadObject.ts"],"sourcesContent":["import type { Awaitable } from '@unshared/functions/awaitable'\nimport type { Reactive, ReactiveOptions } from '@unshared/reactivity/reactive'\nimport type { FSWatcher, PathLike, Stats, WatchOptions } from 'node:fs'\nimport { overwrite } from '@unshared/collection/overwrite'\nimport { awaitable } from '@unshared/functions/awaitable'\nimport { reactive } from '@unshared/reactivity/reactive'\nimport { EventEmitter } from 'node:events'\nimport { constants, watch } from 'node:fs'\nimport { access, mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises'\nimport { dirname } from 'node:path'\n\nexport interface FSObjectOptions<T extends object> extends ReactiveOptions<T>, WatchOptions {\n\n  /**\n   * If set to `true` and the file does not exist, the file will be created\n   * if it does not exist and the object will be initialized with an empty\n   * object.\n   *\n   * @default false\n   */\n  createIfNotExists?: boolean\n\n  /**\n   * If set to `true`, the file will be deleted when the instance is destroyed.\n   * Allowing you to create temporary files that will be deleted when the\n   * instance is garbage collected.\n   */\n  deleteOnDestroy?: boolean\n\n  /**\n   * If set to `true`, changes on the file will not be reflected in the object.\n   * You can use this to prevent the object from being updated when you are\n   * making changes to the file.\n   *\n   * @default false\n   */\n  ignoreFileChanges?: boolean\n\n  /**\n   * If set to `true`, changes on the object will be reflected in the file.\n   * You can set this to `false` if you want to make multiple changes to the\n   * object without triggering multiple file updates.\n   *\n   * @default false\n   */\n  ignoreObjectChanges?: boolean\n\n  /**\n   * The initial value of the object. If the file does not exist, the object\n   * will be initialized with this value.\n   *\n   * @default {}\n   */\n  initialValue?: T\n\n  /**\n   * The parser function to use when reading the file. If not set, the file\n   * will be parsed as JSON using the native `JSON.parse` function.\n   *\n   * @default JSON.parse\n   */\n  parse?: (json: string) => T\n\n  /**\n   * The stringifier function to use when writing the file. If not set, the\n   * object will be stringified as JSON using the native `JSON.stringify` function.\n   *\n   * @default JSON.stringify\n   */\n  serialize?: (object: T) => string\n}\n\nexport interface FSObjectEventMap<T extends object> {\n  commit: [T]\n  destroy: []\n  load: [T]\n  lock: []\n  unlock: []\n}\n\n// eslint-disable-next-line unicorn/prefer-event-target\nexport class FSObject<T extends object> extends EventEmitter<FSObjectEventMap<T>> {\n\n  /** Flag to signal the file is synchronized with the object. */\n  public isCommitting = false\n\n  /** Flag to signal the instance has been destroyed. */\n  public isDestroyed = false\n\n  /** Flag to signal the object is synchronized with the file. */\n  public isLoading = false\n\n  /** The current content of the file. */\n  public object: Reactive<T>\n\n  /** The current status of the file. */\n  public stats: Stats | undefined\n\n  /** A watcher that will update the object when the file changes. */\n  public watcher: FSWatcher | undefined\n\n  /**\n   * Load a JSON file and keep it synchronized with it's source file.\n   *\n   * @param path The path or file descriptor of the file to load.\n   * @param options Options for the watcher.\n   * @throws {Error} if the file cannot be accessed or parsed.\n   */\n  constructor(public path: PathLike, public options: FSObjectOptions<T> = {}) {\n    super()\n\n    // --- The callback that will be called when the object changes.\n    // --- This callback is wrapped in a debounce function to prevent\n    // --- multiple writes in a short period of time.\n    const callback = async() => {\n      if (this.isBusy) return\n      if (this.options.ignoreObjectChanges) return\n      await this.commit()\n    }\n\n    // --- Create the reactive object. Each time a nested property is\n    // --- changed, the callback will be called with the new object.\n    this.object = reactive(this.options.initialValue ?? {} as T, {\n      callbacks: [callback],\n      deep: true,\n      hooks: ['push', 'pop', 'shift', 'unshift', 'splice', 'sort', 'reverse'],\n      ...this.options,\n    })\n  }\n\n  /**\n   * Close the file and stop watching the file and object for changes.\n   * If the file has been created as a temporary file, it will be deleted.\n   *\n   * @returns A promise that resolves when the file has been destroyed.\n   */\n  async [Symbol.asyncDispose]() {\n    return this.destroy()\n  }\n\n  /**\n   * Create an awaitable instance of `FSObject` that resolves when the file\n   * is synchronized with the object and the object is synchronized with the file.\n   *\n   * This function is a shorthand for creating a new `FSObject` instance and\n   * calling the `access`, `load` and `watch` methods in sequence. This allows\n   * fast and easy access to the file and object in a single call.\n   *\n   * @param path The path or file descriptor of the file to load.\n   * @param options Options to pass to the `FSObject` constructor.\n   * @returns An awaitable instance of `FSObject`.\n   * @example\n   * const fsObject = FSObject.from('file.json')\n   * const object = await fsObject\n   *\n   * // Change the file and check the object.\n   * writeFileSync('file.json', '{\"foo\":\"bar\"}')\n   * await fsObject.untilLoaded\n   * object // => { foo: 'bar' }\n   *\n   * // Change the object and check the file.\n   * object.foo = 'baz'\n   * await fsObject.untilCommitted\n   * readFileSync('file.json', 'utf8') // => { \"foo\": \"baz\" }\n   */\n  static from<T extends object>(path: PathLike, options: FSObjectOptions<T> = {}): Awaitable<FSObject<T>, Reactive<T>> {\n    const fsObject = new FSObject<T>(path, options)\n    const createPromise = () => fsObject.load().then(() => fsObject.watch().object)\n    return awaitable(fsObject, createPromise)\n  }\n\n  /**\n   * Commit the current state of the object to the file. This function\n   * **will** write the object to the file and emit a `commit` event.\n   *\n   * @param writeObject The object to write to the file.\n   * @returns A promise that resolves when the file has been written.\n   */\n  public async commit(writeObject = this.object as T): Promise<void> {\n    this.isCommitting = true\n\n    // --- Stringify the object and write it to disk.\n    const { serialize = (object: unknown) => JSON.stringify(object, undefined, 2) } = this.options\n    const writeJson = serialize(writeObject)\n    const pathString = this.path.toString()\n    const pathDirectory = dirname(pathString)\n    await mkdir(pathDirectory, { recursive: true })\n    await writeFile(this.path, `${writeJson}\\n`, 'utf8')\n    overwrite(this.object, writeObject)\n    this.stats = await stat(this.path)\n\n    this.emit('commit', writeObject)\n    this.isCommitting = false\n  }\n\n  /**\n   * Close the file and stop watching the file and object for changes.\n   * If the file has been created as a temporary file, it will be deleted.\n   */\n  public async destroy(): Promise<void> {\n    this.isLoading = false\n    this.isCommitting = false\n    if (this.watcher) this.watcher.close()\n    if (this.options.deleteOnDestroy) await rm(this.path, { force: true })\n    this.watcher = undefined\n    this.isDestroyed = true\n    this.emit('destroy')\n  }\n\n  /**\n   * Load the file and update the object.\n   *\n   * @returns The loaded object.\n   */\n  public async load(): Promise<void> {\n    this.isLoading = true\n    this.isDestroyed = false\n\n    // --- If the file does not exist, and the `createIfNotExists` option is\n    // --- set to `true`, create the file and initialize the object with the\n    // --- `initialValue` option.\n    const accessError = await access(this.path, constants.F_OK | constants.R_OK).catch((error: Error) => error)\n    if (accessError && this.options.createIfNotExists) {\n      await this.commit()\n      this.isLoading = false\n      this.emit('load', this.object)\n      return\n    }\n\n    // --- If the file does not exist, throw an error.\n    if (accessError && !this.options.createIfNotExists) throw accessError\n\n    // --- Assert the path points to a file.\n    const newStats = await stat(this.path)\n    const newIsFile = newStats.isFile()\n    if (!newIsFile) throw new Error(`Expected ${this.path.toString()} to be a file`)\n\n    // --- If the file has not changed, return the current object.\n    if (this.object && this.stats && newStats.mtimeMs < this.stats.mtimeMs) return\n    this.stats = newStats\n\n    // --- Read and parse the file.\n    const { parse = JSON.parse } = this.options\n    const newJson = await readFile(this.path, 'utf8')\n    const newObject = parse(newJson) as T\n\n    // --- Assert JSON is an object.\n    if (typeof newObject !== 'object' || newObject === null)\n      throw new Error(`Expected ${this.path.toString()} to be a JSON object`)\n\n    // --- Update the object by overwriting it's properties.\n    overwrite(this.object, newObject)\n    this.isLoading = false\n    this.emit('load', newObject)\n  }\n\n  /**\n   * Start watching the file for changes and update the object if the content\n   * of the file changes.\n   *\n   * @returns The current instance for chaining.\n   * @example\n   * const object = new FSObject('file.json').watch()\n   *\n   * // Change the file and check the object.\n   * writeFileSync('file.json', '{\"foo\":\"bar\"}')\n   *\n   * // Wait until the object is updated.\n   * await object.untilLoaded\n   *\n   * // Check the object.\n   * expect(object.object).toStrictEqual({ foo: 'bar' })\n   */\n  public watch(): this {\n    if (this.watcher) return this\n\n    // --- Try to watch the file for changes. If an error occurs, the file\n    // --- is likely not accessible. In this case, just set the `isWatching`\n    // --- flag to `true` and retry watching the file when it becomes accessible.\n    this.watcher = watch(this.path, { persistent: false, ...this.options }, (event) => {\n      if (this.isBusy) return\n      if (this.options.ignoreFileChanges) return\n      if (event === 'change') void this.load()\n    })\n\n    // --- Return the instance for chaining.\n    return this\n  }\n\n  /**\n   * Flag to signal the instance is busy doing a commit or a load operation.\n   *\n   * @returns `true` if the instance is busy, `false` otherwise.\n   */\n  get isBusy() {\n    return this.isLoading || this.isCommitting || this.isDestroyed\n  }\n\n  /**\n   * A promise that resolves when the file is synchronized with the object.\n   *\n   * @returns A promise that resolves when the file is synchronized.\n   * @example\n   * const object = new FSObject('file.json')\n   * object.commit()\n   *\n   * // Wait until the file is synchronized.\n   * await object.untilCommitted\n   */\n  get untilCommitted(): Promise<void> {\n    if (!this.isCommitting) return Promise.resolve()\n    return new Promise<void>(resolve => this.prependOnceListener('commit', () => resolve()))\n  }\n\n  /**\n   * A promise that resolves when the object is destroyed.\n   *\n   * @returns A promise that resolves when the object is destroyed.\n   * @example\n   * const object = new FSObject('file.json')\n   * object.destroy()\n   *\n   * // Wait until the object is destroyed.\n   * await object.untilDestroyed\n   */\n  get untilDestroyed(): Promise<void> {\n    if (this.isDestroyed) return Promise.resolve()\n    return new Promise<void>(resolve => this.prependOnceListener('destroy', resolve))\n  }\n\n  /**\n   * A promise that resolves when the object is synchronized with the file.\n   *\n   * @returns A promise that resolves when the file is synchronized.\n   * @example\n   * const object = new FSObject('file.json')\n   * object.load()\n   *\n   * // Wait until the object is synchronized.\n   * await object.untilLoaded\n   */\n  get untilLoaded(): Promise<void> {\n    if (!this.isLoading) return Promise.resolve()\n    return new Promise<void>(resolve => this.prependOnceListener('load', () => resolve()))\n  }\n}\n\n/**\n * Create an awaitable instance of `FSObject` that resolves when the file\n * is synchronized with the object and the object is synchronized with the file.\n *\n * This function is a shorthand for creating a new `FSObject` instance and\n * calling the `access`, `load` and `watch` methods in sequence. This allows\n * fast and easy access to the file and object in a single call.\n *\n * @param path The path or file descriptor of the file to load.\n * @param options Options to pass to the `FSObject` constructor.\n * @returns An awaitable instance of `FSObject`.\n * @example\n * const fsObject = loadObject('file.json')\n * const object = await fsObject\n *\n * // Change the file and check the object.\n * writeFileSync('file.json', '{\"foo\":\"bar\"}')\n * await fsObject.untilLoaded\n * object // => { foo: 'bar' }\n *\n * // Change the object and check the file.\n * object.foo = 'baz'\n * await fsObject.untilCommitted\n * readFileSync('file.json', 'utf8') // => { \"foo\": \"baz\" }\n */\nexport function loadObject<T extends object>(path: PathLike, options: FSObjectOptions<T> = {}): Awaitable<FSObject<T>, Reactive<T>> {\n  return FSObject.from(path, options)\n}\n"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@unshared/fs",
   "type": "module",
-  "version": "0.7.3",
+  "version": "0.7.5",
   "license": "MIT",
   "sideEffects": false,
   "author": "Stanley Horwood <stanley@hsjm.io>",
@@ -77,14 +77,14 @@
     "README.md",
     "LICENSE.md"
   ],
-  "dependencies": {
-    "@unshared/collection": "0.7.3",
-    "@unshared/functions": "0.7.3",
-    "@unshared/reactivity": "0.7.3",
-    "@unshared/string": "0.7.3",
-    "@unshared/types": "0.7.3"
+  "peerDependencies": {
+    "memfs": ">=4.0.0"
   },
-  "devDependencies": {
-    "memfs": "4.36.3"
+  "dependencies": {
+    "@unshared/collection": "0.7.5",
+    "@unshared/functions": "0.7.5",
+    "@unshared/reactivity": "0.7.5",
+    "@unshared/string": "0.7.5",
+    "@unshared/types": "0.7.5"
   }
 }