@eighty4/velcro v0.0.9

Velcro for Elasticsearch

Create Elasticsearch indices, mappings and documents -- without any code!

No frills, no config!

It's so 0.0.6, it can't even be configured for an Elasticsearch node other than localhost or a node that needs authentication!

CLI

The CLI currently has one subcommand: velcro strap.

Setup methods

Install globally

npm i -g velcro
velcro strap

Or npx it

npx velcro strap

Or add an npm script and npm run velcro it

{
  "scripts": {
    "velcro": "velcro strap"
  },
  "devDependencies": {
    "velcro": "0.0.6"
  }
}

strap command

velcro strap will create all indices, mappings and documents found in the current working directory's velcro.yaml file

---
indices:
  my-index-name:
    properties:
      a_field_name: keyword
      another_field: text
  my-other-index:
    properties:
      created_when: date

Indexing documents with velcro strap

The documents key in velco.yaml contains yaml sequences of documents organized by environment and index name. A document may include an id by specifying it with the _id key and nesting the document's fields under the doc key.

Documents under documents.all will be created any time velcro strap is run.

---
indices:
  my-index-name:
    properties:
      a_field_name: keyword
      another_field: text

documents:
  all:
    my-index-name:
      - _id: foobar
        doc:
          a_field_name: MY_VERY_OWN_ID
          another_field: this doc is created with a specified id
      - a_field_name: GENERATED_DOC_ID
        another_field: this doc's id will be generated by elasticsearch
      - a_field_name: GENERATED_DOC_ID
        another_field: this structure will also create a doc with an elasticsearch generated id

Creating documents for a specific environment, such as test, can be done by running velcro strap --env test and nesting documents under documents.test in velcro.yaml:

documents:
  test:
    my-index-name:
      - a_field_name: CREATED
        another_field: velcro strap --env test will create this doc
  prod:
    my-index-name:
      - a_field_name: SKIPPED
        another_field: velcro strap --env test will omit this doc
  all:
    my-index-name:
      - a_field_name: CREATED
        another_field: velcro strap will always create docs nested under all

Testing

createVelcroTestStrap

A test strap manages indices and mappings for execution of a test. Indices are created with an alternate name to isolate test state from previous executions.

import {createVelcroTestStrap} from 'velcro'

const velcro = await createVelcroTestStrap({
    elasticsearch: {client},
    indices: ['my-index-name'],
    documents: [
        {
            a_field_name: "value",
            another_field: "text",
        }
    ]
})

// do some testing

await velcro.cleanup()

createVelcroTestStrap will refresh indices that documents were created in, so they're ready to be searched when createVelcroTestStrap completes.

Created index names and document ids can be retrieved using VelcroTestStrap.managedIndexName(), VelcroTestStrap.documentIds() and VelcroTestStrap.documentId().

velcroTestStrap.managedIndexName('my-index-name') will return the index name used to isolate testing from other data and operations during the scope of the test.

velcroTestStrap.documentsIds('my-index-name') will return an array of all document ids created for the specified index.

velcroTestStrap.documentsId('my-index-name', 0) will return a specific document id using the index of the array in createVelcroTestStrap's opts.documents array.

📌 createVelcroTestStrap reads velcro.yaml to create indices and mappings and has an option configPath to reference a velcro.yaml file outside the test's cwd. Only indices referenced in the createVelcroTestStrap indices option will be created, and no documents from velcro.yaml will be created.

Caveats

velcro strap currently deletes and re-creates indices and is not meant for production data management.

Only happy paths and no testing. Bugs gauranteed!