Class Veloce<TData>

constructor

• new Veloce<TData = unknown>(
      filePath: string,
      baseData: TData,
      configuration?: {
          autoSave?: boolean;
          autoSaveDelayMs?: number;
          fileOptions?: WriteFileOptions;
          indentation?: null | string | number;
          maxAutoSaveTimeouts?: number;
          noProxy?: boolean;
          onUpdate?: (
              method:
                  | "get"
                  | "set"
                  | "deleteProperty"
                  | "defineProperty"
                  | "setPrototypeOf"
                  | "apply"
                  | "construct"
                  | "has"
                  | "ownKeys"
                  | "getOwnPropertyDescriptor"
                  | "preventExtensions"
                  | "isExtensible"
                  | "getPrototypeOf",
              result: unknown,
          ) => void;
          saveRetryTimeoutMs?: number;
          useSync?: boolean;
      },
  ): Veloce<TData>

  Creates a new Veloce database instance.

  Type Parameters

  • TData = unknown

  Parameters

  • filePath: string

    The path to the database file
  • baseData: TData

    The base data to use as fallback when no data exists
  • configuration: {
        autoSave?: boolean;
        autoSaveDelayMs?: number;
        fileOptions?: WriteFileOptions;
        indentation?: null | string | number;
        maxAutoSaveTimeouts?: number;
        noProxy?: boolean;
        onUpdate?: (
            method:
                | "get"
                | "set"
                | "deleteProperty"
                | "defineProperty"
                | "setPrototypeOf"
                | "apply"
                | "construct"
                | "has"
                | "ownKeys"
                | "getOwnPropertyDescriptor"
                | "preventExtensions"
                | "isExtensible"
                | "getPrototypeOf",
            result: unknown,
        ) => void;
        saveRetryTimeoutMs?: number;
        useSync?: boolean;
    } = {}

    Configuration options for the database

    • OptionalautoSave?: boolean

      Whether data should be automatically saved to the database. This feature only works in proxy mode.

      Default

      true
      Copy

    • OptionalautoSaveDelayMs?: number

      When auto-saving is enabled, the database will wait for this duration (in milliseconds) before saving the data. If modified again during this period, the timer resets.

      Default

      750
      Copy

    • OptionalfileOptions?: WriteFileOptions

      File system options used when saving data to the database file.

      Default

      { encoding: "utf-8" }
      Copy

    • Optionalindentation?: null | string | number

      The number of spaces for indentation when saving the file.

      Default

      2
      Copy

    • OptionalmaxAutoSaveTimeouts?: number

      Maximum number of consecutive auto-save timeouts before forcing a save operation.

      Default

      10
      Copy

    • OptionalnoProxy?: boolean

      Whether the database should use no-proxy mode. The no-proxy mode disables many features for a more streamlined process. This mode is more optimized, but requires manual data saving.

      Default

      false
      Copy

    • OptionalonUpdate?: (
          method:
              | "get"
              | "set"
              | "deleteProperty"
              | "defineProperty"
              | "setPrototypeOf"
              | "apply"
              | "construct"
              | "has"
              | "ownKeys"
              | "getOwnPropertyDescriptor"
              | "preventExtensions"
              | "isExtensible"
              | "getPrototypeOf",
          result: unknown,
      ) => void

      Callback function triggered on data updates (only in proxy mode). Receives the update method name and operation result.

      Default

      undefined
      Copy

    • OptionalsaveRetryTimeoutMs?: number

      The timeout in milliseconds before retrying to save the data if any issues occur.

      Default

      100
      Copy

    • OptionaluseSync?: boolean

      Whether to use synchronous file operations by default. If false, asynchronous operations will be used.

      Default

      false
      Copy

  Returns Veloce<TData>

data

close

• close(): Promise<void>

  Closes the database instance, cancelling any pending saves and cleaning up resources. After closing, no further operations will be performed.

  Returns Promise<void>

delete

• delete(): void

  Deletes the database file from the filesystem synchronously. This operation cannot be undone.

  Returns void

deleteAsync

• deleteAsync(): Promise<void>

  Deletes the database file from the filesystem asynchronously. This operation cannot be undone.

  Returns Promise<void>

reload

• reload(): void

  Reloads the data from the file synchronously.

  Returns void

reloadAsync

• reloadAsync(): Promise<void>

  Reloads the data from the file asynchronously.

  Returns Promise<void>

save

• save(force?: boolean): void

  Saves the current state of the database to the file synchronously.

  Parameters

  • force: boolean = false

    If true, bypasses all checks and immediately saves the data

  Returns void

saveAsync

• saveAsync(force?: boolean): Promise<void>

  Saves the current state of the database to the file asynchronously.

  Parameters

  • force: boolean = false

    If true, bypasses all checks and immediately saves the data

  Returns Promise<void>