IF Commons GitHub

sql/describe/mod

Written to: 6 requirements: 6 proved, 0 partly, 0 failing, 0 with no test recorded. 0057-sql-describe FR-001, 0057-sql-describe FR-002, 0057-sql-describe FR-003, 0057-sql-describe FR-004, 0057-sql-describe FR-005, 0057-sql-describe FR-006

Describing models in layers (commons data 0057-sql-describe): the models of governance, the logical schema that projects from them and the physical forms of that schema (SQL for each dialect, the typed tables of 0053) as plain data a documentation generator reads. One LayeredModel for each module: its elements in each layer with their stable ids, the words the model gives them, where they are written and what is said of them; the trace from an element to what it is made into; and the findings (what has no definition, personal data that is held for no purpose). It is pure: it imports no documentation library and returns values that are checked against the generator's types by their shape alone.

The layers are written for a developer and for an agent: each says what it is, which code writes it and what may be edited, so that the generated pages say how to use the layers and not only what they hold.

Source: commons/data/sql/describe/mod.ts

3 of 8 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

Layerinterfaceno test imports it
interface Layer

A layer of a model.

MemberTypeWhat it is
idstring
titlestring
summarystring
kindsreadonly string[]
Traceinterfaceno test imports it
interface Trace

An element made into another.

MemberTypeWhat it is
fromstring
tostring
howstring
Describedinterfaceno test imports it
interface Described

A model described in layers: structurally the generator's LayeredModel.

MemberTypeWhat it is
namestring
librarystring
titlestring
summarystring
subject?{ readonly id: string; readonly title: string; readonly about: string; readonly order: number; }What the model applies to (subjectOf of governance), where it has a subject.
layersreadonly Layer[]
elementsreadonly Element[]
tracereadonly Trace[]
findingsreadonly Finding[]
DescribeOptionsinterfaceno test imports it
interface DescribeOptions

What describing is told.

MemberTypeWhat it is
modulesreadonly Module[]The modules of the composition, in the order they are composed.
dialectsreadonly Dialect[]The dialects whose SQL is shown.
library?stringThe library the models are of, as the site names it.
domain?stringThe name of the domain the modules are composed into; models where not given.
naming?Naming
locate?((value: unknown, member?: string | undefined) => Source | undefined)Where a value is written (a module, a concept, a code list) and, for a member of a concept, where it is: the generator's lens finds them from the exports it knows.
typedDir?stringWhere the generated typed tables are, relative to the repository's root; commons/data/sql/typed/models where not given.
DescribeErrortypeno test imports it
type DescribeError = { readonly kind: "compose" | "project" | "bind"; readonly why: string };

Why a description could not be made.

LAYERSconst
const LAYERS: readonly Layer[]

The layers, with what each is for and how to use it.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

typeTextfunction
function typeText(t: Datatype): string

A datatype in words.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

describeModelsfunction
function describeModels(options: DescribeOptions): Result<readonly Described[], DescribeError>

Describes the models of a composition in layers.

ParameterWhat it is
optionsthe modules, the dialects and where things are written

Returns: one described model for each module that owns a table or a concept, or why the composition could not be made

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.