fix: more descriptive accessor method names

NOTE that this is technically breaking change, but since it is early (still unused) release, only patch version will be bumped.

Author: mdvorak

README.md

@@ -62,7 +62,7 @@ import * as properties from 'js-java-properties'
 const props = properties.empty()
 props.lines.push('key1=value1', 'key2 = value2', 'key3: value3')
 
-for (const {key, value} of properties.list(props)) {
+for (const {key, value} of properties.listProperties(props)) {
   console.log(`${key}=${value}`)
   // key1=value1
   // key2=value2
@@ -83,7 +83,7 @@ import * as properties from 'js-java-properties'
 const props = properties.empty()
 props.lines.push('key1=value1', 'key2 = value2', 'key3: value3')
 
-console.log(properties.get(props, 'key2'))
+console.log(properties.getProperty(props, 'key2'))
 // 'value2'
 ```
 
@@ -115,19 +115,19 @@ import * as properties from 'js-java-properties'
 const props = properties.empty()
 props.lines.push('key1=value1', 'key2 = value2', 'key3: value3')
 
-properties.set(props, 'key2', 'new-value')
+properties.setProperty(props, 'key2', 'new-value')
 console.log(properties.stringify(props))
 // 'key1=value1\nkey2 = new-value\nkey3: value3\n'
 
-properties.set(props, 'new-key', 'new-value')
+properties.setProperty(props, 'new-key', 'new-value')
 console.log(properties.stringify(props))
 // 'key1=value1\nkey2 = new-value\nkey3: value3\nnew-key=new-value\n'
 
-properties.set(props, 'new-key', 'new-value', {separator: ':'})
+properties.setProperty(props, 'new-key', 'new-value', {separator: ':'})
 console.log(properties.stringify(props))
 // 'key1=value1\nkey2 = new-value\nkey3: value3\nnew-key:new-value\n'
 
-properties.set(props, 'key3', undefined)
+properties.setProperty(props, 'key3', undefined)
 console.log(properties.stringify(props))
 // 'key1=value1\nkey2 = new-value\n'
 ```
@@ -142,7 +142,7 @@ import * as properties from 'js-java-properties'
 const props = properties.empty()
 props.lines.push('key1=value1', 'key2 = value2', 'key3: value3')
 
-properties.remove(props, 'key2')
+properties.removeProperty(props, 'key2')
 console.log(properties.stringify(props))
 // 'key1=value1\nkey3: value3\n'
 ```

src/properties.spec.ts

@@ -112,16 +112,16 @@ describe('data access', () => {
     ['foo23', 'bar23']
   ]
 
-  describe('get value', () => {
+  describe('getProperty', () => {
     it.each(samplePairs)('should get property "%s"', (key, expected) => {
-      const result = properties.get(sample, key)
+      const result = properties.getProperty(sample, key)
       expect(result).toBe(expected)
     })
 
     it.each([['foo6'], ['foo7']])(
       'should not get commented property "%s"',
       key => {
-        const result = properties.get(sample, key)
+        const result = properties.getProperty(sample, key)
         expect(result).toBeUndefined()
       }
     )
@@ -131,7 +131,7 @@ describe('data access', () => {
         lines: ['key1=foo1', 'key2=foo2', 'key1=foo3']
       }
 
-      const result = properties.get(config, 'key1')
+      const result = properties.getProperty(config, 'key1')
       expect(result).toBe('foo3')
     })
 
@@ -140,7 +140,7 @@ describe('data access', () => {
         lines: ['foo\\u23a=bar']
       }
 
-      expect(() => properties.get(config, 'foo')).toThrowError()
+      expect(() => properties.getProperty(config, 'foo')).toThrowError()
     })
 
     it.each([['foo=bar\\u23a'], ['foo=bar\\u23ax5']])(
@@ -150,7 +150,7 @@ describe('data access', () => {
           lines: [line]
         }
 
-        expect(() => properties.get(config, 'foo')).toThrowError()
+        expect(() => properties.getProperty(config, 'foo')).toThrowError()
       }
     )
 
@@ -165,12 +165,12 @@ describe('data access', () => {
         lines: [line]
       }
 
-      const result = properties.get(config, 'foo')
+      const result = properties.getProperty(config, 'foo')
       expect(result).toBe(value)
     })
   })
 
-  describe('set value', () => {
+  describe('setProperty', () => {
     it.each([
       ['foo1', 'bar', 'foo1=bar'],
       ['foo8:', 'bar8', 'foo8\\:=bar8'],
@@ -187,7 +187,7 @@ describe('data access', () => {
       ['foo22', '\\', 'foo22=\\\\']
     ])('should format key pair for "%s"', (key, value, expected) => {
       const config = properties.empty()
-      properties.set(config, key, value)
+      properties.setProperty(config, key, value)
       expect(config.lines).toEqual([expected])
     })
 
@@ -202,7 +202,7 @@ describe('data access', () => {
       const config: properties.Properties = {
         lines: [line]
       }
-      properties.set(config, 'a', 'b')
+      properties.setProperty(config, 'a', 'b')
       expect(config.lines).toEqual([line, expected])
     })
 
@@ -232,7 +232,7 @@ describe('data access', () => {
         'foo22',
         'foo23'
       ]
-      keys.forEach(key => properties.set(sample, key, 'x'))
+      keys.forEach(key => properties.setProperty(sample, key, 'x'))
 
       expect(sample.lines).toEqual([
         'foo0=x',
@@ -268,7 +268,7 @@ describe('data access', () => {
         lines: ['key1=foo1', 'key2=foo2']
       }
 
-      properties.set(config, 'key1', 'test', {separator: ': '})
+      properties.setProperty(config, 'key1', 'test', {separator: ': '})
       expect(config.lines).toEqual(['key1: test', 'key2=foo2'])
     })
 
@@ -277,25 +277,25 @@ describe('data access', () => {
         lines: ['key1=foo1', 'key2=foo2', 'key1=foo3']
       }
 
-      properties.set(config, 'key1', 'test')
+      properties.setProperty(config, 'key1', 'test')
       expect(config.lines).toEqual(['key1=test', 'key2=foo2'])
     })
-  })
 
-  describe('remove value', () => {
     it('should remove existing key with set undefined', () => {
       const config: properties.Properties = {
         lines: ['foo=bar']
       }
-      properties.set(config, 'foo', undefined)
+      properties.setProperty(config, 'foo', undefined)
       expect(config.lines).toEqual([])
     })
+  })
 
+  describe('removeProperty', () => {
     it('should remove existing key with remove', () => {
       const config: properties.Properties = {
         lines: ['foo=bar']
       }
-      properties.remove(config, 'foo')
+      properties.removeProperty(config, 'foo')
       expect(config.lines).toEqual([])
     })
 
@@ -304,14 +304,14 @@ describe('data access', () => {
         lines: ['key1=foo1', 'key2=foo2', 'key1=foo3']
       }
 
-      properties.remove(config, 'key1')
+      properties.removeProperty(config, 'key1')
       expect(config.lines).toEqual(['key2=foo2'])
     })
   })
 
-  describe('list', () => {
+  describe('listProperties', () => {
     it('should list all key-value pairs', () => {
-      const result = [...properties.list(sample)]
+      const result = [...properties.listProperties(sample)]
       const resultAsArrays = result.map(({key, value}) => [key, value])
 
       expect(resultAsArrays).toEqual(samplePairs)
@@ -322,7 +322,7 @@ describe('data access', () => {
         lines: ['foo=bar1', 'foo=bar2']
       }
 
-      const result = [...properties.list(config)]
+      const result = [...properties.listProperties(config)]
       expect(result).toEqual([
         {key: 'foo', value: 'bar1'},
         {key: 'foo', value: 'bar2'}
@@ -368,46 +368,46 @@ describe('data access', () => {
         ['c', 'd']
       ])
     })
+  })
+
+  it('should parse test file', async () => {
+    const contents = await fs.readFile(
+      require.resolve('../fixtures/test-all.properties'),
+      'utf-8'
+    )
 
-    it('should parse test file', async () => {
-      const contents = await fs.readFile(
-        require.resolve('../fixtures/test-all.properties'),
-        'utf-8'
-      )
-
-      // Parse
-      const result = properties.toObject(properties.parse(contents))
-
-      // Verify
-      expect(result).toEqual({
-        '': 'So does this line.',
-        category: 'file format',
-        duplicateKey: 'second',
-        empty: '',
-        encodedHelloInJapanese: 'こんにちは',
-        evenKey: 'This is on one line\\',
-        'evenLikeThis\\': '',
-        hello: 'hello',
-        helloInJapanese: 'こんにちは',
-        こんにちは: 'hello',
-        keyWithBackslashes: 'This has random backslashes',
-        'keyWithDelimiters:= ':
-          'This is the value for the key "keyWithDelimiters:= "',
-        'keyWitheven\\': 'this colon is not escaped',
-        language: 'English',
-        multiline: 'This line continues on 3 lines',
-        multilineKey: 'this is a multiline key',
-        noWhiteSpace:
-          'The key will be "noWhiteSpace" without any whitespace.    ',
-        oddKey: 'This is line one and\\# This is line two',
-        orLikeThis: '',
-        path: 'c:\\wiki\\templates',
-        topic: '.properties file',
-        valueWithEscapes:
-          'This is a newline\n, a carriage return\r, a tab\t and a formfeed\f.',
-        website: 'https://en.wikipedia.org/',
-        welcome: 'Welcome to Wikipedia!    '
-      })
+    // Parse
+    const result = properties.toObject(properties.parse(contents))
+
+    // Verify
+    expect(result).toEqual({
+      '': 'So does this line.',
+      category: 'file format',
+      duplicateKey: 'second',
+      empty: '',
+      encodedHelloInJapanese: 'こんにちは',
+      evenKey: 'This is on one line\\',
+      'evenLikeThis\\': '',
+      hello: 'hello',
+      helloInJapanese: 'こんにちは',
+      '\u3053\u3093\u306B\u3061\u306F': 'hello',
+      keyWithBackslashes: 'This has random backslashes',
+      'keyWithDelimiters:= ':
+        'This is the value for the key "keyWithDelimiters:= "',
+      'keyWitheven\\': 'this colon is not escaped',
+      language: 'English',
+      multiline: 'This line continues on 3 lines',
+      multilineKey: 'this is a multiline key',
+      noWhiteSpace:
+        'The key will be "noWhiteSpace" without any whitespace.    ',
+      oddKey: 'This is line one and\\# This is line two',
+      orLikeThis: '',
+      path: 'c:\\wiki\\templates',
+      topic: '.properties file',
+      valueWithEscapes:
+        'This is a newline\n, a carriage return\r, a tab\t and a formfeed\f.',
+      website: 'https://en.wikipedia.org/',
+      welcome: 'Welcome to Wikipedia!    '
     })
   })
 })

src/properties.ts

@@ -86,7 +86,7 @@ export const stringify = (config: Properties): string => {
  *
  * @param config Java properties set.
  */
-export function* list(config: Properties): Generator<KeyValuePair> {
+export function* listProperties(config: Properties): Generator<KeyValuePair> {
   for (const {key, value} of listPairs(config.lines)) {
     yield {key, value}
   }
@@ -102,7 +102,10 @@ export function* list(config: Properties): Generator<KeyValuePair> {
  * @param key Key name.
  * @return Found value, or undefined. Value is properly unescaped.
  */
-export const get = (config: Properties, key: string): string | undefined => {
+export const getProperty = (
+  config: Properties,
+  key: string
+): string | undefined => {
   let value: string | undefined = undefined
 
   // Find last value
@@ -158,7 +161,12 @@ export const toMap = (config: Properties): Map<string, string> => {
  * @param sep Separator, cannot be empty. Valid chars are ` :=`.
  * @param escapeUnicode Enable/disable unicode escaping.
  */
-const formatLine = (key: string, value: string, sep: string, escapeUnicode: boolean) =>
+const formatLine = (
+  key: string,
+  value: string,
+  sep: string,
+  escapeUnicode: boolean
+) =>
   `${escapeKey(key, escapeUnicode)}${sep}${escapeValue(value, escapeUnicode)}`
 
 /**
@@ -169,26 +177,26 @@ const formatLine = (key: string, value: string, sep: string, escapeUnicode: bool
  * @param value New value. If undefined or null, key will be removed.
  * @param options Optionally override set behavior.
  */
-export const set = (
+export const setProperty = (
   config: Properties,
   key: string,
   value: string | undefined | null,
   options?: {separator?: string}
 ): void => {
   const escapeUnicode = true
-  let lastSep = '='
+  let sep = options?.separator || '='
   let found = false
 
   // Find all entries
   for (const entry of listPairs(config.lines)) {
     // Remember separator
-    if (entry.sep) lastSep = entry.sep
+    if (!options?.separator && entry.sep) sep = entry.sep
 
     // If found, either replace or remove
     if (key === entry.key) {
       const items =
         !found && typeof value === 'string'
-          ? [formatLine(key, value, options?.separator || lastSep, escapeUnicode)]
+          ? [formatLine(key, value, sep, escapeUnicode)]
           : []
 
       config.lines.splice(entry.start, entry.len, ...items)
@@ -198,7 +206,7 @@ export const set = (
 
   // Not found, append
   if (!found && typeof value === 'string') {
-    config.lines.push(formatLine(key, value, options?.separator || lastSep, escapeUnicode))
+    config.lines.push(formatLine(key, value, sep, escapeUnicode))
   }
 }
 
@@ -210,8 +218,8 @@ export const set = (
  * @param config Java properties set.
  * @param key Key name.
  */
-export const remove = (config: Properties, key: string): void =>
-  set(config, key, undefined)
+export const removeProperty = (config: Properties, key: string): void =>
+  setProperty(config, key, undefined)
 
 /**
  * Character iterator over lines of chars.