IF Commons GitHub

sql/extensions/convergence/propose

Written to: 3 requirements: 3 proved, 0 partly, 0 failing, 0 with no test recorded. 0019-sql-convergence FR-004, 0019-sql-convergence FR-005, 0019-sql-convergence FR-006

Proposals (commons data 0019-sql-convergence FR-004 to FR-006): the plan from the state a database is in to the state wanted, pinned to the state it was computed from. A reviewed proposal is a file a person reads and approves; applying it checks that the text is the one that was approved and that the database is still in the state it was pinned to.

Source: commons/data/sql/extensions/convergence/propose.ts

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

applyProposalfunction
function applyProposal(text: string, approved: string, driver: Driver, dialect: Dialect, wanted: State, options?: Omit<RunOptions, "empty"> & { readonly ignore?: readonly string[] | undefined; }): Promise<Result<Applied, readonly ApplyError[]>>

Applies a proposal that was approved.

ParameterWhat it is
textthe proposal's text
approvedthe hash of the text that was approved
driverthe database
dialectits dialect
wantedthe state wanted, to read the database against
optionswhat the run is given and the names the reader leaves out

Returns: what was applied, or why not

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

ApplyErrortypeno test imports it
type ApplyError =
  | { readonly kind: "unapproved"; readonly approved: string; readonly actual: string }
  | { readonly kind: "unreadable"; readonly why: string }
  | { readonly kind: "read"; readonly errors: readonly ReadError[] }
  | { readonly kind: "stale"; readonly pinned: string; readonly found: string }
  | RunError;

What is wrong with applying one.

desiredStatefunction
function desiredState(schema: LogicalSchema, desired: Desired): State | undefined

The state wanted, as a value.

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

proposefunction
function propose(driver: Driver, schema: LogicalSchema, desired: Desired, options?: ProposeOptions): Promise<Result<{ readonly proposal: Proposal; readonly plan: Plan; readonly live: State; readonly wanted: State; }, readonly ProposeError[]>>

The plan from the state a database is in to the state wanted, pinned.

ParameterWhat it is
driverthe database
schemathe logical schema wanted
desiredthe dialect, naming, schema and what extensions add
optionswhat plan is given, and the names the reader leaves out

Returns: the proposal and what it is made of, or why not

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

Proposalinterfaceno test imports it
interface Proposal

A plan pinned to the state it was computed from.

MemberTypeWhat it is
format1
dialectstring
basestringThe hash of the state the database was in.
tostringThe hash of the state the plan ends in.
stepsreadonly ProposalStep[]
held?readonly string[]What is in the database and not in the model, and is held: no step touches it.
repeatablereadonly { readonly key: string; readonly hash: string; readonly of: readonly string[]; readonly statements: readonly StepStatement[]; }[]
ProposalStepinterfaceno test imports it
interface ProposalStep

A step as a proposal holds it.

MemberTypeWhat it is
numbernumber
idstring
namestring
kindstring
classstring
why?string
reversibilitystring
idempotency?string
fromstring
tostring
ofreadonly string[]
upreadonly StepStatement[]
down?readonly StepStatement[]
verify?Verification
ProposeErrortypeno test imports it
type ProposeError =
  { readonly kind: "read"; readonly errors: readonly ReadError[] } | { readonly kind: "plan"; readonly errors: readonly PlanError[] };

What is wrong with a proposal.

ProposeOptionsinterfaceno test imports it
interface ProposeOptions extends PlanOptions

What a proposal is made with.

MemberTypeWhat it is
ignore?readonly string[]The names of tables the reader leaves out, besides the ledger's.
ledgerTable?stringThe ledger's table; lifecycle_ledger by default.
allow?{ readonly destructive?: boolean | undefined; }
fallback?FallbackMakes what the core cannot make in place, such as a table that is made again.
manual?readonly ManualStep[]
transforms?readonly StepTransform[]
requireIdempotent?booleanRefuse, as an error value, a step that is only safe to run twice because of the ledger (0012-sql-idempotency FR-007).
proposalTextconst
const proposalText: (p: Proposal) => string

The text a person approves: the proposal, the same every time.

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

renderProposalfunction
function renderProposal(p: Proposal, stem: string): readonly Artifact[]

The files of a proposal: the text that is approved and a page to read it by.

ParameterWhat it is
pthe proposal
stemwhat the files are called

Returns: the files

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

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