deepest-lore

Tools for creating and managing your deepest lore.

Data model

deepest-lore uses a mini-"relational database", wherein information is organized into tables of rows and columns.

Entity

An entity represents a "thing", with a unique, invariant identifier.

For instance, you might have an entity per recipe, or per ingredient.

Mapping

A mapping specifies information for a unique combination of entities.

For instance, you might map ingredients to recipes.

Identifier

An identifier is a string 6 characters in length using the character set _abcdefghijklmnopqrstuvwxyz0123456789.

These would usually not be shown to the end-user, but instead be used to keep consistent references between versions. As such, they should be invariant (never change).

Binary representation

Identifiers can be stored as an unsigned 32-bit integer.

The range 0-4095999999 is reserved for current and future characters, but the range 4096000000-4294967295 will never be generated from a six-character string, and can safely be used for "special" values.

Examples

| Six-character string | 32-bit integer | |----------------------|----------------| | ______ | 0 | | zzzzzz | 3780923076 | | for_eg | 1704192617 |

Localizations

Schema documents define a set of localizations, which have identifiers.

Any information which is localized is then specified once per localization, keyed by its identifier.

Disk import

All files are expected to be UTF-8 encoded.

{base directory}/schema.json

The schema, as defined in @deepest-lore/data-model.

{base directory}/entities/{entity type identifier}.csv

Each row defines a single entity instance while the first row defines the columns. The following patterns are supported:

| Pattern | Meaning | |-----------------|--------------------------------------------------------------------------------------------------| | $ | The column defines the entity instance's unique identifier. | | col_id | The column defines the value of unlocalized entity type column col_id. | | col_id:loc_id | The column defines the value of localized entity type column col_id for localization loc_id. |

Example

$,name__:en_gb_,name__:fr_fr_,catgry,weapon,food__,salqty,weight
grpfrt,Grapefruit,Pamplemousse,fruit_,❌,✔️,1,5
lemon_,Lemon,Citron,fruit_,TRUE,Yes,4,2
pebble,Pebble,Caillou,rock__,FALSE,No,50,1

| $ | name__:en_gb_ | name__:fr_fr_ | catgry | weapon | food__ | salqty | weight | |--------|---------------|---------------|--------|--------|--------|--------|--------| | grpfrt | Grapefruit | Pamplemousse | fruit_ | ❌ | ✔️ | 1 | 5 | | lemon_ | Lemon | Citron | fruit_ | TRUE | Yes | 4 | 2 | | pebble | Pebble | Caillou | rock__ | FALSE | No | 50 | 1 |

{base directory}/mappings/{mapping identifier}.csv

Similarly to entity type files, each row defines a single mapping while the first row defines the columns. The following patterns are supported:

| Pattern | Meaning | |-----------------|--------------------------------------------------------------------------------------------------| | $key_id | The column defines the mapping key key_id. | | col_id | The column defines the value of unlocalized entity type column col_id. | | col_id:loc_id | The column defines the value of localized entity type column col_id for localization loc_id. |

Example

$item__,$vendor,price_
lemon_,grngcr,0.8
pebble,grngcr,0.5
grpfrt,grngcr,2.4
pebble,rocrus,0.4

| $item__ | $vendor | price_ | |---------|---------|--------| | lemon_ | grngcr | 0.8 | | pebble | grngcr | 0.5 | | grpfrt | grngcr | 2.4 | | pebble | rocrus | 0.4 |

HTML export

/index.html

Shows the schema document's description and a list of all entity types.

/entity-types/{entity type identifier}/index.html

Shows the entity type's description and a list of all its instances.

/entity-types/{entity type identifier}/instances/{entity instance identifier}

Shows the entity instance's column values and a list of all entity and mapping instances which reference it.

Validation

Errors raised on failure

• The schema document matches the JSON schema.
• All entity reference columns reference an existing entity type.
• All entity reference column defaults refer to an existing instance of their referenced entity type.
• All entity reference column values refer to an existing instance of their referenced entity type.
• All mapping keys reference existing entity types in schema.
• All mapping keys reference existing entity instances of their referenced entity type in data.
• All entity type labels are resolvable; each run is a chain of existing entity reference columns, excepting the last, which is any existing column on the final entity.
• All localized values include every localization defined at the root of the schema document.
• All integer column maximum values are at least their minimum values.
• All integer column default values fall between (inclusively) their minimum and maximum values.
• All integer column values fall between (inclusively) their minimum and maximum values.
• All float column maximum values are at least their minimum values.
• All float column default values fall between (inclusively) their minimum and maximum values.
• All float column values fall between (inclusively) their minimum and maximum values.
• All string column default values fit within their maximum length.
• All string column values fit within their maximum length.

Warnings raised on failure.

• Localized values include no localizations not defined at the root of the schema document.
• No unexpected columns are found within entity type or mapping data.
• All entity types have at least one instance.
• All mappings have at least one instance.

Command-line interface

Warnings will be printed but do not count as an error by default.

Example: deepest-lore {parameters}.

Parameters

--fs-import {path}

The base directory from which to import; runs once then stops. Exits on error and returns a non-zero exit code.

Uses @deepest-lore/fs-import.

--fs-import-watch {path}

The base directory from which to import; runs once then waits for changes before running again until terminated by the user. Aborts run but does not exit on error.

Uses @deepest-lore/fs-import-watch.

--warnings-as-errors

When present, any warnings generated by @deepest-lore/validator will instead be treated as errors. The standard error handling logic will then apply.

--html-export {path}

The base directory to which to export; this will be deleted and replaced with a new directory containing the exported HTML.

Watch builds will not be minified.

Uses @deepest-lore/html-export.

License