Storage

This R Package provides a standard interface for performing data operations on various data stores. Currently, a memory and odbc driver-based Storage is supported. To configure an odbc driver-based data store, an ODBC.Configurator is available to retrieve the required configuration parameters from a local .Renviron file. Lastly, this package includes an example service in which a Storage instance is injected into to enable persistence.

Below is an overview of the different functions available on each of the components:

ODBC Configurator

Two utility functions are provided:

1. open.config.file
   Opens the .Renviron file in your IDE. This function only works when using either VS Code or RStudio.

2. get.config
   Retrieves the configuration parameters from your local .Renviron file. By default a preset configuration is assumed when an OS DSN has been set up. A preset type configuration assumes a DSN, UID and PWD variables have been defined in the .Renviron file. If no OS DSN has been set up, get.config can be invoked with type = 'Manual' flag. When retrieving configuration parameters using the type = 'Manual' flag it is assumed DRIVER, SERVER, DATABASE, UID, PWD variables have been defined in the .Renviron file.

Storage Component

Six functions are provided, five of which are common data operations and one function to execute custom queries:

1. add
2. retrieve
3. retrieve.where.id
4. modify
5. remove

Custom data operations can be added using the execute.query function. The execute.query function takes a SQL query, passed in as a character data type, and returns a data frame.

Lastly, the retrieve.where.id and modify operations assumes the data model has an id attribute. The id attribute is used to uniquely identify a record in the data store.

Todo Data Service

Five functions are provided:

1. add
2. retrieve
3. retrieve.where.id
4. modify
5. remove

The Todo.Service is an example of how to use the Storage component. The Todo.Service is a simple data service that performs CRUD operations on a Todo data model.

Note: This package is a Standard compliant package.

Installation

At the time of writing this README, the package is not available on CRAN. However, it can be installed using devtools.

Install Dependencies

1. This package has two dependencies: Validate, Environment, Query:

devtools::install_github("https://github.com/FlippieCoetser/Validate")
devtools::install_github("https://github.com/FlippieCoetser/Environment")
devtools::install_github("https://github.com/FlippieCoetser/Query")

Install via GitHub

1. Use Devtools

devtools::install_github("https://github.com/FlippieCoetser/Storage")

Clone, Build and Install Locally

1. Clone the repository

git clone https://github.com/FlippieCoetser/Storage.git

2. Build and Generate .tar.gz file

devtools::build()

3. Install the package

install.packages("path_to_file/tar_gz_file", repos = NULL, type = "source")

Loading the Package

There are two ways to load the package:

1. Use the library function to load all available components into the global namespace
2. Create a new instance of a component using the package namespace

User Global Namespace

Three components are loaded into the global namespace when using the library function to load the package.

library(Storage)

User Package Namespace

When using the package namespace, the three components can be accessed as follows:

Storage::ODBC.Configurator()
Storage::Storage()
Storage::Todo.Service()

Usage

Using the Todo.Service component, two use cases will be demonstrated, one using a memory data store and the other using an odbc data store.

Initialize

In-Memory Data Store

1. Create an empty configuration

configuration <- list()

2. Create a new instance of the Storage component with type = 'memory'.

storage <- configuration |> Storage::Storage(type = 'memory')

ODBC Data Store

Note: Two types of configuration sets are support for odbc data stores: Preset and Manual. Where Preset require additional operating system configuration

1. Create a new instance of ODBC.Configurator

odbc.configurator <- Storage::ODBC.Configurator()

2. retrieve the configuration parameters from the local .Renviron file

configuration <- odbc.configurator[['get.config']]()

3. Create a new instance of Storage component.

storage <- configuration |> Storage::Storage()

Use Cases

1. When using a storage with a memory based store, seed the store with mock data

table <- 'Todo'
todos <- data.frame(
  id     = c('7ab3df6f-2e8f-44b4-87bf-3004cf1c16ae',
            '7bfef861-6fe9-46da-9ad2-6a58779ccdcd',
            'd3b59bf0-14f0-4444-9ec9-1913e7256ee4'),
  task   = c('Task.1','Task.2','Task.3'),
  status = c('New','New','Done')
)

todos |> storage[['seed.table']](table)

2. select a storage instance based on your desired data store and create a new Todo.Service instance

todo.service <- storage |> Todo.Broker() |> Todo.Service()

Add Todo

1. Create a new todo

todo <- 'Task' |> Todo()

2. Add the todo into the data store

todo |> todo.service[['add']]()

retrieve Todos

1. retrieve all todos in the data store

todos <- todo.service[['retrieve']]()

retrieve Todo Where Id

1. Use the todo created in a previous step and extract its id

id   <- todo[['id']]

2. retrieve the todo with the extracted id

todo <- id |> todo.service[['retrieve.where.id']]()

modify Todo

1. Use the todo retrieved in the previous step and update its status

todo[['status']] <- "Done"

2. modify the todo in the data store

todo |> todo.service[['modify']]()

remove Todo

1. Use the todo retrieved in the previous step and extract its id

id <- todo[['id']]

2. remove the todo with the extracted id

id |> todo.service[['remove']]()