SRI

The Codedraw generic template uses the SRI or System Record Identifier to determine where to find or store records a.k.a. Mongo Documents. The SRI is a string that describes:

1. The name of the entity which will match the collection name in your MongoDB instance. This is a required field.
2. The identifier that uniquely identify a document in your MongoDB collection, it matches the _id field in a MongoDb Document. This is an optional field.
3. The override name tells the backend to use your custom code to interact with the MongoDB collection. This is an optional field. The override field must always start with __.
4. The arguments the same as a url query string that allows you to specify additional field that you can access in your override function. This is an optional field.

The Identifier and Override fields are mutually exclusive.

String format

The SRI is a __ separated string where the left describes the name and the right either the identifier or the override. Let's have a look at some examples:

The following sri string describes a document that's found in the book collection with an _id of 5f838f99-dfd2-4735-b3db-03587799c469

const sri: string = 'book__5f838f99-dfd2-4735-b3db-03587799c469'

The following sri string invokes a custom override it will return all the books from the book collection that have been liked by me.

const sri: string = 'book____liked_by_me'

The following sri describes another custom override that finds all the books from the book collection where the author matches the author_id in the query string.

const sri: string = 'book____by_author?author_id=7d3ca513-74c9-4e61-9069-45494ec42412'

Object structure

Here is what an SRI looks like when parsed from a string into an object:

export declare interface SRI {
  /**
   * The name of the record
   */
  name: string
  /**
   * The identifier of the record (must be unique)
   */
  identifier?: string
  /**
   * The override used to identify a data override function to run for this record
   */
  override?: string
  /**
   * The arguments to pass to the data override function
   */
  arguments?: URLSearchParams
  /**
   * Returns a string representation of this SRI as `name__identifier`
   */
  toString(): string
}

It's important to note that any sri field attached to a document is transient. The SRI field is never stored.

Available utils

Build an SRI

/**
 * Build an SRI object from a name, identifier and key
 *
 * @param name the name of the record
 * @param options the options to build the SRI
 * @returns an SRI object
 */
export declare const build: (name: string, options: Either<BuildOptions>) => SRI;

Parse an SRI

/**
 * Parse a string into an SRI object.
 * This method validates that the SRI has the correct format. NOTE: the validation will not pick up if you
 * invert the identifier or override with the name.
 * A valid SRI must start with the name first, followed by an optional identifier or override.
 *
 * @param value the SRI string to parse
 * @returns an SRI object
 */
export declare const parse: (value: string) => SRI;

Arguments

When building an SRI you either supply an identifier or a override but you cannot supply both.

export declare type BuildOptions = {
  /**
   * The unique identifier of the record
   */
  identifier?: string;
  /**
   * The override used to identify a a data override function to run for this record
   */
  override?: string;
}

Example usages

import { SRI } from '@coderpunktech/codedraw-client'

const sri: SRI.SRI = SRI.build('book', { identifier: 'a022b53f-2090-4b8d-8dbc-2cc3b714c602' })
// toString -> book__a022b53f-2090-4b8d-8dbc-2cc3b714c602

const withOverride: SRI.SRI = SRI.build('book', { override: 'liked_by_me' })
// toString -> book____liked_by_me

const withArguments: SRI.SRI = SRI.build('book', { override: 'by_author?author_id=43bdfa62-0539-4675-8884-8b0602c5ba1d' })
// toString -> book____by_author?author_id=43bdfa62-0539-4675-8884-8b0602c5ba1d

const parsed: SRI.SRI = SRI.parse('book__a022b53f-2090-4b8d-8dbc-2cc3b714c602')