json-fs-query 0.1.0 → 0.1.1

package/src/data/introspect/definitions/key.test.js

@@ -1,100 +0,0 @@
-import { key } from './key'
-
-describe('key', () => {
-  test('can generate a primary key', () => {
-    const primaryKey = {
-      type: 'primary',
-      fields: [
-        '_id'
-      ],
-      lookup: 'pk__id.json'
-    }
-    expect(key(primaryKey)).toEqual(primaryKey)
-  })
-
-  test('can generate an index key', () => {
-    const indexKey = {
-      type: 'index',
-      fields: [
-        'date'
-      ],
-      lookup: 'index_date.json'
-    }
-    expect(key(indexKey)).toEqual(indexKey)
-  })
-
-  test('can generate an unique key', () => {
-    const uniqueKey = {
-      type: 'unique',
-      fields: [
-        'email'
-      ],
-      lookup: 'unique_email.json'
-    }
-    expect(key(uniqueKey)).toEqual(uniqueKey)
-  })
-
-  test('can generate a multi key', () => {
-    const multiKey = {
-      type: 'multi',
-      fields: [
-        'email',
-        'user_id'
-      ],
-      lookup: 'multi_email_user_id.json'
-    }
-    expect(key(multiKey)).toEqual(multiKey)
-  })
-
-  test('can generate a foreign key', () => {
-    const foreignKey = {
-      type: 'foreign',
-      fields: [
-        'user_id'
-      ],
-      lookup: 'fk_user_id.json',
-      references: [
-        {
-          fields: [
-            'users._id'
-          ],
-          lookup: 'users.json'
-        }
-      ]
-    }
-    expect(key(foreignKey)).toEqual(foreignKey)
-  })
-
-  test('will throw Error for invalid multi, insufficient fields', () => {
-    const multiKey = {
-      type: 'multi',
-      fields: [
-        'email'
-      ],
-      lookup: 'multi_email_user_id.json'
-    }
-    expect(() => key(multiKey)).toThrow(Error)
-  })
-
-  test('will throw Error for invalid foreign, insufficient references', () => {
-    const foreignKey = {
-      type: 'foreign',
-      fields: [
-        'user_id'
-      ],
-      lookup: 'fk_user_id.json'
-    }
-    expect(() => key(foreignKey)).toThrow(Error)
-  })
-
-  test('will throw Error for unknown key type', () => {
-    const strangeKey = {
-      type: 'strange',
-      fields: [
-        'blah'
-      ],
-      lookup: 'strange_blah.json'
-    }
-    expect(() => key(strangeKey)).toThrow(Error)
-  })
-})

package/src/data/introspect/definitions/key.ts

@@ -1,64 +0,0 @@
-import { keyReference, reference } from './keyReference'
-import { fieldName } from './field'
-
-export type indexType = string
-
-export type indexLocation = string
-
-export type keyDefinition = {
-  type: indexType
-  fields: Array<fieldName>
-  lookup: indexLocation
-  references?: Array<reference>
-}
-
-export type keyProperties = {
-  type?: indexType
-  fields?: Array<fieldName>
-  lookup?: indexLocation
-  references?: Array<reference>
-}
-
-/**
- * Create a field key.
- * @param properties
- * @param properties.type
- * @param properties.fields
- * @param properties.lookup
- * @param properties.references
- */
-export const key = ({
-  type = 'index',
-  fields = [],
-  lookup = '',
-  references = []
-}: keyProperties = {}): keyDefinition => {
-  switch (type) {
-    case 'primary':
-    case 'index':
-    case 'unique':
-      references = []
-      break
-    case 'multi':
-      if (fields.length < 2) {
-        throw new Error('Multi key indicated with less than two fields')
-      }
-      break
-    case 'foreign':
-      if (references.length < 1) {
-        throw new Error('Foreign key must have one reference to an external record')
-      }
-      break
-    default:
-      throw new Error('Unrecognized key type; must be index, primary, unique, multi, or foreign')
-  }
-  const keyDefinition = {
-    type: type,
-    fields: fields,
-    lookup: lookup
-  }
-  if (typeof references !== 'undefined' && references.length > 0) {
-    keyDefinition['references'] = references.map(keyReference)
-  }
-  return keyDefinition
-}

package/src/data/introspect/definitions/keyReference.test.js

@@ -1,8 +0,0 @@
-import { keyReference } from './keyReference'
-
-describe('keyReference', () => {
-  test('can generate a reference', () => {
-    const reference = { fields: ['exercises._id'], lookup: 'exercises.json' }
-    expect(keyReference(reference)).toEqual(reference)
-  })
-})

package/src/data/introspect/definitions/keyReference.ts

@@ -1,23 +0,0 @@
-import { fieldName } from './field'
-import { recordPath } from './record'
-
-export type reference = {
-  fields: fieldName[];
-  lookup: recordPath;
-}
-
-export type referenceProperties = {
-  fields?: fieldName[];
-  lookup?: recordPath;
-}
-
-/**
- * Create a reference to a remote (foreign; existing on another record) key.
- * @param properties
- * @param properties.fields
- * @param properties.lookup
- */
-export const keyReference = ({ fields = [], lookup = '' }: referenceProperties = {}): reference => ({
-  fields: fields,
-  lookup: lookup
-})

package/src/data/introspect/definitions/record.ts

@@ -1,42 +0,0 @@
-import { field, fieldDefinition, fieldProperties } from './field'
-import { key, keyDefinition, keyProperties } from './key'
-
-export type recordPath = string
-
-export type entityPath = string
-
-export type recordDefinition = {
-  path: recordPath
-  definition: fieldDefinition[]
-  keys: keyDefinition[]
-  entries: entityPath[]
-}
-
-export type recordProperties = {
-  path?: recordPath
-  definition?: fieldProperties[]
-  keys?: keyProperties[]
-  entries?: entityPath[]
-}
-
-/**
- *
- * @param properties
- * @param properties.path
- * @param properties.definition
- * @param properties.keys
- * @param properties.entries
- */
-export const record = ({
-  path = '',
-  definition = [],
-  keys = [],
-  entries = []
-}: recordProperties = {}): recordDefinition => {
-  return {
-    path: path,
-    definition: definition.map(field),
-    keys: keys.map(key),
-    entries: entries
-  }
-}

package/src/data/introspect/describe.test.js

@@ -1,36 +0,0 @@
-import { create } from './create'
-import { describe as describeRecord } from './describe'
-import { testHelpers } from 'js-build-tools/testHelpers'
-
-const databasePath = 'describe-database/'
-const gulpConfig = testHelpers.gulpConfig
-gulpConfig.set('databasePath', databasePath)
-testHelpers.setDefaults(databasePath)
-
-beforeEach(testHelpers.beforeEach)
-
-afterEach(testHelpers.afterEach)
-
-const definition = [
-  { name: '_id', type: 'string', optional: false, autoGenerate: true },
-  { name: 'bar', type: 'string', optional: true, autoGenerate: false }
-]
-
-const keys = [
-  { type: 'primary', fields: ['_id'], lookup: 'pk__id.json' }
-]
-
-describe('describe', () => {
-  test('describes a record by returning its field definition', async () => {
-    await create('foo', definition, keys)
-    const result = await describeRecord('foo')
-    expect(result).toEqual(definition)
-  })
-
-  test('describes __RECORDS by returning the list of known records', async () => {
-    await create('foo', definition, keys)
-    await create('bar', definition, keys)
-    const result = await describeRecord()
-    expect(result).toEqual(['foo.json', 'bar.json'])
-  })
-})

package/src/data/introspect/describe.ts

@@ -1,9 +0,0 @@
-import { retrieveFile } from '../utilities/retrieveFile'
-
-export const describe = async (record = '__RECORDS') => {
-  const recordFile = await retrieveFile(`${record}.json`)
-  if (record === '__RECORDS') {
-    return recordFile.entries
-  }
-  return recordFile.definition
-}

package/src/data/introspect/drop.test.js

@@ -1,77 +0,0 @@
-import { create } from './create'
-import { drop } from './drop'
-import { insertEntity } from '../queries/insertEntity'
-import { testHelpers } from 'js-build-tools/testHelpers'
-
-const { writeFile, readFile } = require('fs/promises')
-
-const databasePath = 'drop-database/'
-const gulpConfig = testHelpers.gulpConfig
-gulpConfig.set('databasePath', databasePath)
-testHelpers.setDefaults(databasePath)
-
-beforeEach(testHelpers.beforeEach)
-
-afterEach(testHelpers.afterEach)
-
-describe('drop', () => {
-  test('returns null for the reserved __RECORDS name, without touching anything', async () => {
-    expect(await drop('__RECORDS')).toBeNull()
-  })
-
-  test('removes every entry file listed on the record', async () => {
-    const recordName = 'foo'
-    await create(recordName, [], [])
-    // insertEntity is not implemented yet, so simulate a real entry directly: write the data file, and record it
-    // on the record's own entries list, exactly as a working insertEntity would.
-    const entryFile = 'entry1.json'
-    await writeFile(`${databasePath}${recordName}/${entryFile}`, JSON.stringify({ _id: 1 }))
-    const recordContent = JSON.parse(await readFile(`${databasePath}${recordName}.json`, 'utf8'))
-    recordContent.entries = [entryFile]
-    await writeFile(`${databasePath}${recordName}.json`, JSON.stringify(recordContent))
-
-    expect(testHelpers.fileExists(`${databasePath}${recordName}/${entryFile}`)).toBeTruthy()
-    await drop(recordName)
-    expect(testHelpers.fileExists(`${databasePath}${recordName}/${entryFile}`)).toBeFalsy()
-  })
-
-  test('deregisters the record from __RECORDS', async () => {
-    await create('foo', [], [])
-    await create('bar', [], [])
-    await drop('foo')
-    const registry = JSON.parse(await readFile(`${databasePath}__RECORDS.json`, 'utf8'))
-    expect(registry.entries).toEqual(['bar.json'])
-  })
-
-  test('removes the record\'s own definition file and data directory', async () => {
-    await create('foo', [], [])
-    expect(testHelpers.fileExists(`${databasePath}foo.json`)).toBeTruthy()
-    expect(testHelpers.fileExists(`${databasePath}foo`)).toBeTruthy()
-
-    await drop('foo')
-
-    expect(testHelpers.fileExists(`${databasePath}foo.json`)).toBeFalsy()
-    expect(testHelpers.fileExists(`${databasePath}foo`)).toBeFalsy()
-  })
-
-  test('removes the record\'s own index directory', async () => {
-    const definition = [
-      { name: '_id', type: 'string', optional: false, autoGenerate: true }
-    ]
-    const keys = [
-      { type: 'primary', fields: ['_id'], lookup: 'pk__id.json' }
-    ]
-    await create('foo', definition, keys)
-    await insertEntity('foo', [{}], {})
-    expect(testHelpers.fileExists(`${databasePath}__indexes/foo/pk__id.json`)).toBeTruthy()
-
-    await drop('foo')
-
-    expect(testHelpers.fileExists(`${databasePath}__indexes/foo`)).toBeFalsy()
-  })
-
-  test('does not throw when the record has no index directory to remove', async () => {
-    await create('foo', [], [])
-    await expect(drop('foo')).resolves.not.toThrow()
-  })
-})

package/src/data/introspect/drop.ts

@@ -1,20 +0,0 @@
-import { retrieveFile } from '../utilities/retrieveFile'
-import { deregisterRecord } from '../utilities/deregisterRecord'
-
-const gulpConfig = require('js-build-tools/gulp.config')
-const { rm } = require('fs/promises')
-
-export const drop = async (record) => {
-  const databasePath = gulpConfig.get('databasePath', 'database/')
-  if (record === '__RECORDS') {
-    return null
-  }
-  const recordFile = await retrieveFile(`${record}.json`)
-  for (const file of recordFile.entries) {
-    await rm(`${databasePath}${recordFile.path}/${file}`)
-  }
-  await rm(`${databasePath}${recordFile.path}`, { recursive: true, force: true })
-  await rm(`${databasePath}__indexes/${recordFile.path}`, { recursive: true, force: true })
-  await rm(`${databasePath}${record}.json`)
-  await deregisterRecord(record)
-}

package/src/data/introspect/index.ts

@@ -1,8 +0,0 @@
-export { create } from './create'
-export { drop } from './drop'
-export { describe } from './describe'
-
-export { fieldProperties, fieldDefinition, fieldName } from './definitions/field'
-export { keyProperties, keyDefinition, indexType, indexLocation } from './definitions/key'
-export { referenceProperties, reference } from './definitions/keyReference'
-export { recordProperties, recordDefinition, recordPath, entityPath } from './definitions/record'

package/src/data/introspect/policies/foreignKeyExists.test.js

@@ -1,44 +0,0 @@
-import { create } from '../create'
-import { insertEntity } from '../../queries/insertEntity'
-import { foreignKeyExists } from './foreignKeyExists'
-import { testHelpers } from 'js-build-tools/testHelpers'
-
-const databasePath = 'foreign-key-exists-database/'
-const gulpConfig = testHelpers.gulpConfig
-gulpConfig.set('databasePath', databasePath)
-testHelpers.setDefaults(databasePath)
-
-beforeEach(testHelpers.beforeEach)
-
-afterEach(testHelpers.afterEach)
-
-const definition = [
-  { name: '_id', type: 'string', optional: false, autoGenerate: true },
-  { name: 'name', type: 'string', optional: true, autoGenerate: false }
-]
-
-const keys = [
-  { type: 'primary', fields: ['_id'], lookup: 'pk__id.json' }
-]
-
-describe('foreignKeyExists', () => {
-  test('returns true when a record has the given property set to the given value', async () => {
-    await create('exercises', definition, keys)
-    const inserted = await insertEntity('exercises', [{ name: 'Bench Press' }], {})
-    const exists = await foreignKeyExists('exercises', '_id', inserted.exercises[0]._id)
-    expect(exists).toBe(true)
-  })
-
-  test('returns false when no record matches', async () => {
-    await create('exercises', definition, keys)
-    await insertEntity('exercises', [{ name: 'Bench Press' }], {})
-    const exists = await foreignKeyExists('exercises', '_id', 'does-not-exist')
-    expect(exists).toBe(false)
-  })
-
-  test('returns false for an entity with no entries', async () => {
-    await create('exercises', definition, keys)
-    const exists = await foreignKeyExists('exercises', '_id', 'anything')
-    expect(exists).toBe(false)
-  })
-})

package/src/data/introspect/policies/foreignKeyExists.ts

@@ -1,15 +0,0 @@
-import { retrieveRecords } from '../../utilities/retrieveRecords'
-import { where } from '../../queries/where'
-
-/**
- * Check whether any record in the referenced entity has the given property set to the given
- * value - the mirror image of keyUnique(), which checks that no record already has a value.
- * @param entity
- * @param property
- * @param value
- */
-export const foreignKeyExists = async (entity: string, property: string, value: any): Promise<boolean> => {
-  const records = await retrieveRecords(entity)
-  const found = where(records, { property, comparator: '=', value })
-  return found.length > 0
-}

package/src/data/introspect/policies/keyGenerate.ts

@@ -1,11 +0,0 @@
-import { keyUnique } from './keyUnique'
-
-export const keyGenerate = async (entity, references = []) => {
-  let uuid = null
-  let isUnique = false
-  while (!isUnique) {
-    uuid = crypto.randomUUID()
-    isUnique = await keyUnique(entity, references, uuid)
-  }
-  return uuid
-}

package/src/data/introspect/policies/keyUnique.ts

@@ -1,11 +0,0 @@
-import { retrieveRecords } from '../../utilities/retrieveRecords'
-import { where } from '../../queries/where'
-
-export const keyUnique = async (entity, references = [], checkKey = null) => {
-  if (references.length !== 1) {
-    return false
-  }
-  const records = await retrieveRecords(entity)
-  const found = where(records, { property: references[0], comparator: '=', value: checkKey })
-  return !found.length
-}

package/src/data/introspect/policies/typeCheck.test.js

@@ -1,84 +0,0 @@
-import { typeCheck } from './typeCheck'
-
-describe('typeCheck', () => {
-  test('passes an undefined value through unchanged, for optional fields', () => {
-    expect(typeCheck('string', undefined)).toBeUndefined()
-  })
-
-  test('does not constrain an unrecognized type name', () => {
-    expect(typeCheck('whatever', 42)).toBe(42)
-  })
-
-  describe('string', () => {
-    test('leaves an existing string alone', () => {
-      expect(typeCheck('string', 'foo')).toBe('foo')
-    })
-
-    test('coerces a non-string to a string', () => {
-      expect(typeCheck('string', 42)).toBe('42')
-    })
-  })
-
-  describe('int', () => {
-    test('leaves an existing integer alone', () => {
-      expect(typeCheck('int', 42)).toBe(42)
-    })
-
-    test('coerces a numeric string to a number', () => {
-      expect(typeCheck('int', '42')).toBe(42)
-    })
-
-    test('rejects a non-integer number', () => {
-      expect(() => typeCheck('int', 4.2)).toThrow('Value "4.2" is not a valid int')
-    })
-
-    test('rejects a value that cannot be coerced to a number', () => {
-      expect(() => typeCheck('int', 'not a number')).toThrow('Value "not a number" is not a valid int')
-    })
-  })
-
-  describe('boolean', () => {
-    test('leaves an existing boolean alone', () => {
-      expect(typeCheck('boolean', false)).toBe(false)
-    })
-
-    test('coerces the strings "true"/"false" to real booleans', () => {
-      expect(typeCheck('boolean', 'true')).toBe(true)
-      expect(typeCheck('boolean', 'false')).toBe(false)
-    })
-
-    test('rejects anything else', () => {
-      expect(() => typeCheck('boolean', 'yes')).toThrow('Value "yes" is not a valid boolean')
-    })
-  })
-
-  describe('object', () => {
-    test('accepts a plain object', () => {
-      const value = { a: 1 }
-      expect(typeCheck('object', value)).toBe(value)
-    })
-
-    test('rejects null', () => {
-      expect(() => typeCheck('object', null)).toThrow('Value "null" is not a valid object')
-    })
-
-    test('rejects an array', () => {
-      expect(() => typeCheck('object', [])).toThrow('is not a valid object')
-    })
-
-    test('rejects a primitive', () => {
-      expect(() => typeCheck('object', 'foo')).toThrow('is not a valid object')
-    })
-  })
-
-  describe('array', () => {
-    test('accepts an array', () => {
-      const value = [1, 2, 3]
-      expect(typeCheck('array', value)).toBe(value)
-    })
-
-    test('rejects a non-array', () => {
-      expect(() => typeCheck('array', { a: 1 })).toThrow('is not a valid array')
-    })
-  })
-})

package/src/data/introspect/policies/typeCheck.ts

@@ -1,49 +0,0 @@
-/**
- * Validate (and where sensible, coerce) a value against a field's declared type. Runs only
- * against values being written by insertEntity/updateEntity - it never re-validates data already
- * on disk, so a field whose declared type doesn't match its already-stored values (which can
- * happen, since nothing enforced this before) is left alone until something actually updates it.
- * An unrecognized type name is treated as unconstrained rather than rejected, so a typo in a
- * schema's field type can't silently block every write to that field.
- * @param type
- * @param value
- */
-export const typeCheck = (type: string = 'string', value: any = undefined): any => {
-  if (typeof value === 'undefined') {
-    return value
-  }
-  switch (type) {
-    case 'string':
-      return typeof value === 'string' ? value : String(value)
-    case 'int': {
-      const coerced = Number(value)
-      if (Number.isNaN(coerced) || !Number.isInteger(coerced)) {
-        throw new Error(`Value "${value}" is not a valid int`)
-      }
-      return coerced
-    }
-    case 'boolean':
-      if (typeof value === 'boolean') {
-        return value
-      }
-      if (value === 'true') {
-        return true
-      }
-      if (value === 'false') {
-        return false
-      }
-      throw new Error(`Value "${value}" is not a valid boolean`)
-    case 'object':
-      if (typeof value !== 'object' || value === null || Array.isArray(value)) {
-        throw new Error(`Value "${value}" is not a valid object`)
-      }
-      return value
-    case 'array':
-      if (!Array.isArray(value)) {
-        throw new Error(`Value "${value}" is not a valid array`)
-      }
-      return value
-    default:
-      return value
-  }
-}

package/src/data/introspect/policies/typeEnum.ts

@@ -1,6 +0,0 @@
-export const typeEnum = (values = [], value = '', optional = false) => {
-  if (values.includes(value)) {
-    return true
-  }
-  return typeof value === 'undefined' && optional
-}

package/src/data/introspect/policies/useDefault.ts

@@ -1,6 +0,0 @@
-export const useDefault = (defaultValue = '', value = undefined) => {
-  if (typeof value === 'undefined') {
-    return defaultValue
-  }
-  return value
-}