@bemoje/cli 0.0.4 → 0.0.6

package/src/db/AbstractJsonFileSection.ts

@@ -0,0 +1,218 @@
+import type { Any } from '../util/types/Any'
+import { defaultOpenInEditorCommand } from '../util/os/defaultOpenInEditorCommand'
+import { JsonFile } from './JsonFile'
+import type { JsonValue } from '../util/types/JsonValue'
+import { promptUserEditJsonInTextEditorSync } from '../util/fs/promptUserEditInTextEditor/promptUserEditJsonInTextEditorSync'
+
+/**
+ * A class that represents a section of the JSON file used as a simple database.
+ */
+export abstract class AbstractJsonFileSection<Val = JsonValue> {
+  /**
+   * Indicates whether the section has been initialized.
+   */
+  protected isInitialized = false
+
+  /**
+   * The default values for the section.
+   */
+  readonly defaultValues: Record<string, Val> = {}
+
+  /**
+   * The base string used as a prefix for the section.
+   */
+  readonly prefixBaseString: string
+
+  /**
+   * Creates an instance of AbstractJsonFileSection.
+   * @param file - The parent JsonFile instance.
+   * @param name - The name of the section.
+   * @param keysAreFixed - Indicates whether the keys in the section are fixed.
+   */
+  constructor(readonly file: JsonFile, protected readonly name: string, protected readonly keysAreFixed: boolean) {
+    this.prefixBaseString = file.cmd.getPrefixArray().join('_')
+  }
+
+  /**
+   * Asserts that a key-value pair is valid.
+   * @param key - The key to assert.
+   * @param value - The value to assert.
+   */
+  abstract assertValid(key: string, value: Val): void
+
+  /**
+   * Defines a property for the section.
+   * @param key - The key of the property.
+   * @param options - The options for the property.
+   */
+  abstract defineProperty(key: string, options: Any): void
+
+  /**
+   * Initializes the section.
+   * @param save - Indicates whether to save the section after initialization.
+   * @returns A string if an error occurred during initialization, otherwise void.
+   */
+  abstract initialize(save?: boolean): void | string
+
+  /**
+   * The JsonDB associated with the section.
+   */
+  get db() {
+    return this.file.db
+  }
+
+  /**
+   * The CommandBuilder associated with the section.
+   */
+  get cmd() {
+    return this.file.cmd
+  }
+
+  /**
+   * Saves the section.
+   * @returns A promise that resolves when the section is saved.
+   */
+  async save() {
+    return await this.db.save()
+  }
+
+  /**
+   * Gets the object path prefix as dot-separated keys for this section of the JSON file database.
+   * @param key - An optional key to append to the prefix path.
+   * @returns The object path prefix.
+   * @throws An error if the keys are fixed and the specified key does not exist in the default values.
+   */
+  prefix(key?: string) {
+    if (this.keysAreFixed && key && !Object.hasOwn(this.defaultValues, key)) {
+      throw new Error(`No entry with key '${key}'`)
+    }
+    return this.prefixBaseString + '.' + this.name + (key ? '.' + key : '')
+  }
+
+  /**
+   * Gets the value associated with the specified key.
+   * @param key - The key to get the value for.
+   * @returns The value associated with the key.
+   */
+  get<T extends Val = Val>(key: string): T {
+    this.initialize(false)
+    return this.db.getSafe<T>(this.prefix(key)) ?? (this.defaultValues[key] as T)
+  }
+
+  /**
+   * Gets all the values in the section.
+   * @returns All the values in the section.
+   */
+  getAll() {
+    this.initialize(false)
+    return (this.db.getSafe(this.prefix()) ?? JSON.parse(JSON.stringify(this.defaultValues))) as Record<string, Val>
+  }
+
+  /**
+   * Gets the keys in the section.
+   * @returns The keys in the section.
+   */
+  get keys() {
+    // if (this.keysAreFixed) return Object.keys(this.defaultValues)
+    return Object.keys(this.getAll())
+  }
+
+  /**
+   * Gets the number of keys in the section.
+   * @returns The number of keys in the section.
+   */
+  count() {
+    return this.keys.length
+  }
+
+  /**
+   * Sets the value associated with the specified key.
+   * @param key - The key to set the value for.
+   * @param value - The value to set.
+   * @param save - Indicates whether to save the section after setting the value.
+   */
+  set(key: string, value: Val, save = true) {
+    this.initialize()
+    this.assertValid(key, value)
+    this.db.set(this.prefix(key), value as JsonValue, save)
+  }
+
+  /**
+   * Sets all the values in the section.
+   * @param values - The values to set.
+   * @param save - Indicates whether to save the section after setting the values.
+   */
+  setAll(values: typeof this.defaultValues, save = true) {
+    const original = this.getAll()
+    for (const [key, value] of Object.entries(values)) {
+      if (value === original[key]) continue
+      if (JSON.stringify(value) === JSON.stringify(original[key])) continue
+      this.set(key, value, false)
+    }
+    if (!this.keysAreFixed) {
+      for (const name of Object.keys(original)) {
+        if (Object.hasOwn(values, name)) continue
+        this.delete(name, false)
+      }
+    }
+    if (save) this.save()
+  }
+
+  /**
+   * Updates the value associated with the specified key.
+   * @param key - The key to set the value for.
+   * @param callback - The callback function that returns the new value.
+   * @param save - Indicates whether to save the section after setting the value.
+   */
+  update(key: string, callback: (val: Val, key: string) => Val, save = true) {
+    this.set(key, callback(this.get(key), key), save)
+  }
+
+  /**
+   * Resets the value associated with the specified key to its default value.
+   * @param key - The key to reset.
+   * @param save - Indicates whether to save the section after resetting the value.
+   */
+  reset(key: string, save = true) {
+    this.set(key, this.defaultValues[key], save)
+  }
+
+  /**
+   * Resets all the values in the section to their default values.
+   * @param save - Indicates whether to save the section after resetting the values.
+   */
+  resetAll(save = true) {
+    this.setAll(this.defaultValues, save)
+  }
+
+  /**
+   * Deletes the value associated with the specified key.
+   * @param key - The key to delete.
+   * @param save - Indicates whether to save the section after deleting the value.
+   */
+  delete(key: string, save = true) {
+    this.initialize()
+    this.db.delete(this.prefix(key), save)
+  }
+
+  /**
+   * Deletes all the values in the section.
+   * @param save - Indicates whether to save the section after deleting the values.
+   */
+  deleteAll(save = true) {
+    for (const key of this.keys) {
+      this.delete(key, false)
+    }
+    if (save) this.save()
+  }
+
+  /**
+   * Edits the values in the section using a text editor.
+   * @param editor - The text editor to use. If not specified, the default text editor command will be used.
+   */
+  edit(editor?: string) {
+    const original = this.getAll()
+    const parsed = promptUserEditJsonInTextEditorSync(original as JsonValue, editor || defaultOpenInEditorCommand())
+    this.setAll(parsed as Record<string, Val>)
+  }
+}

package/src/db/AppDataSection.test.ts

@@ -0,0 +1,69 @@
+import { AppDataSection } from './AppDataSection'
+import { CommandBuilder } from '../cmd/CommandBuilder'
+import { JsonFile } from './JsonFile'
+
+describe(AppDataSection.name, () => {
+  let file: JsonFile
+  let section: AppDataSection
+
+  beforeEach(() => {
+    new CommandBuilder('t', (c) => {
+      file = c.db
+      section = file.appData
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      jest.spyOn(file.db, 'save').mockImplementation((() => {}) as any)
+    })
+  })
+
+  describe('constructor', () => {
+    it('should create an instance of AppDataSection', () => {
+      expect(section).toBeInstanceOf(AppDataSection)
+    })
+
+    it('should set the file property', () => {
+      expect(section.file).toBe(file)
+    })
+  })
+
+  describe('assertValid', () => {
+    it('should do nothing', () => {
+      expect(section.assertValid()).toBeUndefined()
+    })
+  })
+
+  describe('defineProperty', () => {
+    it('should define a property for the section', () => {
+      section.defineProperty('key', 'value')
+      expect(section.defaultValues['key']).toBe('value')
+    })
+
+    it('should clone value', () => {
+      const value = { a: 'value' }
+      section.defineProperty('key', value)
+      expect(section.defaultValues['key']).not.toBe(value)
+      expect(section.defaultValues['key']).toEqual(value)
+    })
+  })
+
+  describe('initialize', () => {
+    it('should do nothing if the section is already initialized', () => {
+      section.initialize()
+      const spy = jest.spyOn(section.db, 'getSafe')
+      section.initialize()
+      expect(spy).not.toHaveBeenCalled()
+    })
+
+    it('should set the values if the section is not initialized', () => {
+      section.defineProperty('key', 'value')
+      section.initialize()
+      expect(section.db.getSafe(section.prefix())).toEqual({ key: 'value' })
+    })
+
+    it('should set the values and save the section if save is true', () => {
+      section.defineProperty('key', 'value')
+      const spy = jest.spyOn(section.db, 'set')
+      section.initialize(true)
+      expect(spy).toBeCalledWith(section.prefix(), { key: 'value' }, true)
+    })
+  })
+})

package/src/db/AppDataSection.ts

@@ -0,0 +1,46 @@
+import { AbstractJsonFileSection } from './AbstractJsonFileSection'
+import { JsonFile } from './JsonFile'
+import type { JsonValue } from '../util/types/JsonValue'
+
+/**
+ * A class that represents the appdata section of the JSON file used as simple database.
+ */
+export class AppDataSection<Val extends JsonValue = JsonValue> extends AbstractJsonFileSection<Val> {
+  /**
+   * Creates an instance of AppDataSection.
+   * @param file - The parent JsonFile instance.
+   * @param name - The name of the section.
+   */
+  constructor(file: JsonFile, name: string) {
+    super(file, name, false)
+  }
+
+  /**
+   * Does nothing
+   */
+  override assertValid() {
+    return
+  }
+
+  /**
+   * Defines a property for the section.
+   * @param key - The key of the property.
+   */
+  override defineProperty(key: string, value: Val) {
+    if (typeof value === 'object') value = JSON.parse(JSON.stringify(value)) as Val
+    this.defaultValues[key] = value
+    this.isInitialized = false
+  }
+
+  /**
+   * Initializes the section.
+   * @param save - Indicates whether to save the section after initialization.
+   * @returns A string if an error occurred during initialization, otherwise void.
+   */
+  override initialize(save = false) {
+    if (this.isInitialized) return
+    const data = this.db.getSafe<Record<string, Val>>(this.prefix())
+    if (!data) this.db.set(this.prefix(), this.defaultValues, save)
+    this.isInitialized = true
+  }
+}

package/src/db/ConfigSection.test.ts

@@ -0,0 +1,95 @@
+import { CommandBuilder } from '../cmd/CommandBuilder'
+import { ConfigSection } from './ConfigSection'
+import { createTypedArrayValidator } from '../util/validation/createTypedArrayValidator'
+import { createTypedListParser } from '../util/string-parsers/createTypedListParser'
+import { isInteger } from '../util/validation/numbers/isInteger'
+import { JsonFile } from './JsonFile'
+import { parseInteger } from '../util/string-parsers/parseInteger'
+
+describe(ConfigSection.name, () => {
+  let file: JsonFile
+  let section: ConfigSection
+  const intConfigOptions = {
+    description: 'info',
+    defaultValue: 1,
+    parse: parseInteger,
+    validate: isInteger,
+  }
+  const intsConfigOptions = {
+    description: 'info',
+    defaultValue: [1],
+    parse: createTypedListParser(',', parseInteger),
+    validate: createTypedArrayValidator([isInteger]),
+  }
+
+  beforeEach(() => {
+    new CommandBuilder('t', (c) => {
+      file = c.db
+      section = file.config
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      jest.spyOn(file.db, 'save').mockImplementation((() => {}) as any)
+    })
+  })
+
+  describe('constructor', () => {
+    it('should create an instance of ConfigSection', () => {
+      expect(section).toBeInstanceOf(ConfigSection)
+    })
+
+    it('should set the file property', () => {
+      expect(section.file).toBe(file)
+    })
+  })
+
+  describe('assertValid', () => {
+    it('should validate', () => {
+      section.defineProperty('key', intConfigOptions)
+      expect(() => section.assertValid('key', 1)).not.toThrow()
+      expect(() => section.assertValid('key', 1.2)).toThrow()
+    })
+  })
+
+  describe('defineProperty', () => {
+    it('should define a property for the section', () => {
+      section.defineProperty('key', intConfigOptions)
+      expect(section.defaultValues['key']).toBe(1)
+      expect(section.parsers['key']).toBe(parseInteger)
+      expect(section.validators['key']).toBe(isInteger)
+      expect(section.descriptions['key']).toBe('info')
+    })
+
+    it('should clone value', () => {
+      section.defineProperty('key', intsConfigOptions)
+      expect(section.defaultValues['key']).not.toBe(intsConfigOptions.defaultValue)
+      expect(section.defaultValues['key']).toEqual(intsConfigOptions.defaultValue)
+    })
+  })
+
+  describe('initialize', () => {
+    it('should do nothing if the section is already initialized', () => {
+      section.initialize()
+      const spy = jest.spyOn(section.db, 'getSafe')
+      section.initialize()
+      expect(spy).not.toHaveBeenCalled()
+    })
+
+    it('should set the values if the section is not initialized', () => {
+      section.defineProperty('key', intConfigOptions)
+      section.initialize()
+      expect(section.getAll()).toEqual({ key: 1 })
+    })
+
+    it('should set the values and save the section if save is true', () => {
+      section.defineProperty('key', intConfigOptions)
+      const spy = jest.spyOn(section.db, 'set')
+      section.initialize(true)
+      expect(spy).toBeCalledWith(section.prefix(), { key: 1 }, true)
+    })
+  })
+
+  describe('prefix', () => {
+    it('should throw if key does not exist', () => {
+      expect(() => section.prefix('nonexistent')).toThrow()
+    })
+  })
+})

package/src/db/ConfigSection.ts

@@ -0,0 +1,74 @@
+import { AbstractJsonFileSection } from './AbstractJsonFileSection'
+import { ensureThat } from '../util/validation/ensureThat'
+import type { IConfig } from '../types/IConfig'
+import { JsonFile } from './JsonFile'
+import type { JsonValue } from '../util/types/JsonValue'
+import { objAssign } from '../util/object/objAssign'
+import type { TStringParser } from '../util/types/TStringParser'
+import type { TValidator } from '../util/types/TValidator'
+
+/**
+ * A class that represents the user-config section of the JSON file used as simple database.
+ */
+export class ConfigSection<Val extends JsonValue = JsonValue> extends AbstractJsonFileSection<Val> {
+  /**
+   * String parsers for when editing config from command-line.
+   */
+  readonly parsers: Record<string, TStringParser<Val>> = {}
+
+  /**
+   * Descriptions for each property key.
+   */
+  readonly descriptions: Record<string, string> = {}
+
+  /**
+   * Validators for each property key.
+   */
+  readonly validators: Record<string, TValidator<Val>> = {}
+
+  /**
+   * Creates an instance of AbstractJsonFileSection.
+   * @param file - The parent JsonFile instance.
+   * @param name - The name of the section.
+   */
+  constructor(file: JsonFile, name: string) {
+    super(file, name, true)
+  }
+
+  /**
+   * Asserts that a key-value pair is valid.
+   * @param key - The key to assert.
+   * @param value - The value to assert.
+   */
+  override assertValid(key: string, value: Val) {
+    if (!this.validators[key]) return
+    ensureThat(value, this.validators[key])
+  }
+
+  /**
+   * Defines a property for the section.
+   * @param key - The key of the property.
+   * @param options - The options for the property.
+   */
+  override defineProperty(key: string, options: IConfig<Val>) {
+    const { description, defaultValue, parse, validate } = options
+    this.descriptions[key] = description
+    this.defaultValues[key] = typeof defaultValue === 'object' ? JSON.parse(JSON.stringify(defaultValue)) : defaultValue
+    if (parse) this.parsers[key] = parse
+    if (validate) this.validators[key] = validate
+    this.assertValid(key, options.defaultValue)
+  }
+
+  /**
+   * Initializes the section.
+   * @param save - Indicates whether to save the section after initialization.
+   * @returns A string if an error occurred during initialization, otherwise void.
+   */
+  override initialize(save = false) {
+    if (this.isInitialized) return
+    const data = this.db.getSafe<Record<string, Val>>(this.prefix())
+    const result = objAssign({}, JSON.parse(JSON.stringify(this.defaultValues)), data || {})
+    this.db.set(this.prefix(), result, save)
+    this.isInitialized = true
+  }
+}

package/src/db/JsonFile.test.ts

@@ -0,0 +1,56 @@
+import { AppDataSection } from './AppDataSection'
+import { CommandBuilder } from '../cmd/CommandBuilder'
+import { ConfigSection } from './ConfigSection'
+import { JsonDB } from '../util/db/JsonDB'
+import { JsonFile } from './JsonFile'
+import { PresetsSection } from './PresetsSection'
+
+describe(JsonFile.name, () => {
+  describe('constructor', () => {
+    it('should return a JsonFile instance', () => {
+      new CommandBuilder('t', (c) => {
+        expect(c.db).toBeInstanceOf(JsonFile)
+      })
+    })
+  })
+
+  describe('db', () => {
+    it('should return a JsonDB instance', () => {
+      new CommandBuilder('t', (c) => {
+        expect(c.db.db).toBeInstanceOf(JsonDB)
+      })
+    })
+
+    it('should return the root commands db if subcommand', () => {
+      new CommandBuilder('t', (c) => {
+        c.command('sub', (s) => {
+          expect(s.db.db).toBe(c.db.db)
+        })
+      })
+    })
+  })
+
+  describe('config', () => {
+    it('should return a ConfigSection instance', () => {
+      new CommandBuilder('t', (c) => {
+        expect(c.db.config).toBeInstanceOf(ConfigSection)
+      })
+    })
+  })
+
+  describe('appData', () => {
+    it('should return a AppDataSection instance', () => {
+      new CommandBuilder('t', (c) => {
+        expect(c.db.appData).toBeInstanceOf(AppDataSection)
+      })
+    })
+  })
+
+  describe('presets', () => {
+    it('should return a PresetsSection instance', () => {
+      new CommandBuilder('t', (c) => {
+        expect(c.db.presets).toBeInstanceOf(PresetsSection)
+      })
+    })
+  })
+})

package/src/db/JsonFile.ts

@@ -0,0 +1,52 @@
+import { AppDataSection } from './AppDataSection'
+import { CommandBuilder } from '../cmd/CommandBuilder'
+import { ConfigSection } from './ConfigSection'
+import { JsonDB } from '../util/db/JsonDB'
+import { PresetsSection } from './PresetsSection'
+import { realizeLazyProperty } from '../util/object/realizeLazyProperty'
+
+/**
+ * A class that represents the JSON file used as a simple database.
+ */
+export class JsonFile {
+  /**
+   * @param cmd The parent CommandBuilder instance.
+   */
+  constructor(readonly cmd: CommandBuilder) {}
+
+  /**
+   * A lazy-loaded instance of the JsonDB instance containing the data.
+   * Upon first property access, it is stored as a property on the instance.
+   * If the command is a subcommand, the root command's JsonDB instance is returned.
+   */
+  get db(): JsonDB {
+    if (this.cmd.isRoot) {
+      return realizeLazyProperty(this, 'db', new JsonDB(this.cmd.dataFilepath, 2))
+    } else {
+      return this.cmd.root.db.db
+    }
+  }
+
+  /**
+   * A lazy-loaded instance of the `config` section of the JSON file.
+   * Upon first property access, it is stored as a property on the instance.
+   */
+  get config(): ConfigSection {
+    return realizeLazyProperty(this, 'config', new ConfigSection(this, 'config'))
+  }
+
+  /**
+   * A lazy-loaded instance of the `appData` section of the JSON file.
+   * Upon first property access, it is stored as a property on the instance.
+   */
+  get appData(): AppDataSection {
+    return realizeLazyProperty(this, 'appData', new AppDataSection(this, 'appData'))
+  }
+
+  /**
+   * A lazy-loaded instance of the `presets` section of the JSON file.
+   */
+  get presets(): PresetsSection {
+    return realizeLazyProperty(this, 'presets', new PresetsSection(this, 'presets'))
+  }
+}