REDCap


classes for interacting with REDCap projects

* REDCapAPI
* REDCapProject
* REDCapProjectInformation
* REDCapField
* REDCapInstrument
* REDCapDatetime

REDCapAPI

an opinionated, JSON-only, zero-dependency REDCap API implementation as an ECMAScript module

$3

``js
import REDCapAPI from '@robireton/redcap/api'

const endpoint = process.env.REDCAP_ENDPOINT
const token = process.env.REDCAP_TOKEN

const project = new REDCapAPI(endpoint, token)
console.log(await project.metadata())
`

$3

#### REDCapAPI(endpoint, token)

| name | value |
| ---- | ----- |
| endpoint | a URL or string to connect to – e.g. https://redcap.server.org/api/ |
| token | the API token specific to your REDCap project and username (each token is unique to each user for each project) |




$3

| name | value |
| ---- | ----- |
| options | an optional object with extra parameters for REDCap API calls |

#### async version()

returns the current REDCap version number as plain text (e.g., 4.13.18, 5.12.2, 6.0.0)

#### async project ()

returns an object with the following fields:

* project_id
* project_title
* creation_time
* production_time
* in_production
* project_language
* purpose
* purpose_other
* project_notes
* custom_record_label
* secondary_unique_field
* is_longitudinal
* has_repeating_instruments_or_events
* surveys_enabled
* scheduling_enabled
* record_autonumbering_enabled
* randomization_enabled
* ddp_enabled
* project_irb_number
* project_grant_number
* project_pi_firstname
* project_pi_lastname
* display_today_now_button
* missing_data_codes
* external_modules
* bypass_branching_erase_field_prompt

#### async metadata (options)

returns an array of data dictionary objects

##### options
* fields: an array of field names specifying specific fields you wish to pull (default: all fields)
* forms: an array of form names specifying specific data collection instruments for which you wish to pull metadata (default: all instruments)

#### async records (options)

returns an array of record objects

##### options
type: flat (default) — one record per row or eav — one data point per row*
* records: an array of record names specifying specific fields you wish to pull (default: all records)
* fields: an array of field names specifying specific fields you wish to pull (default: all fields)
* forms: an array of form names specifying specific data collection instruments for which you wish to pull metadata (default: all instruments)
* events: an array of unique event names that you wish to pull records for (longitudinal projects only)
more… c.f.* full REDCap API specification

#### async events (options)
#### async arms (options)
#### async fields (options)

Returns an array of the export/import-specific version of field name objects for all fields (or for one field, if desired). Each object will contain: original_field_name, choice_value, and export_field_name. The choice_value attribute represents the raw coded value for a checkbox choice. For non-checkbox fields, the choice_value attribute will always be blank/empty. The export_field_name attribute represents the export/import-specific version of that field name.

#### async instruments ()

returns an array of instrument (Data Entry Form) objects

#### async mapping (options)
#### async repeating ()
#### async write (data, options)
#### async file (options)
#### async upload (file, options)




REDCapProject

class for working with project structure and data; uses REDCapAPI or local JSON files

$3


`js
import REDCapAPI from '@robireton/redcap/project'

const endpoint = process.env.REDCAP_ENDPOINT
const token = process.env.REDCAP_TOKEN

const project = new REDCapProject(endpoint, token)
await project.populate()

console.log(project.info.title)
for (const instrument of project.instruments) {
console.log(instrument.label)
for (const record of instrument.records) {
…
}
}
`

$3

#### REDCapProject(endpoint, token)

| name | value |
| ---- | ----- |
| endpoint | a URL or string to connect to – e.g. https://redcap.server.org/api/ |
| token | the API token specific to your REDCap project and username (each token is unique to each user for each project) |

Alternately, if endpoint/token resolves to an existing filesystem folder with appropriately-named JSON files, these will be used instead of REDCapAPI.

$3

#### async populate ()

This must be run before any instance members are accessible.

#### getInstrument` (name)

returns a REDCapInstrument object, which includes the records

REDCapProjectInformation

REDCapField

REDCapInstrument

REDCapDatetime