@antelopejs/interface-dms-builder 0.2.3 → 0.2.5

package/dist/analysis.d.ts

@@ -59,13 +59,15 @@ export interface ProposedResource {
     fields: ProposedField[];
     leftOut: ProposedLeftOut[];
     writes: ProposedWrites;
+    rows?: number;
+    profiledRows?: number;
 }
 export interface ProposedExclusion {
     relation: string;
     reason: string;
     rule: string;
 }
-export type OpenItemKind = "schemas" | "purpose" | "label" | "reference";
+export type OpenItemKind = "schemas" | "purpose" | "label" | "reference" | "field-type";
 export interface OpenItemOption {
     value: unknown;
     title: string;
@@ -79,6 +81,7 @@ export interface OpenItem {
     options: OpenItemOption[];
     proposed: unknown;
     resource?: ProposedResource;
+    open?: OpenItem[];
 }
 export interface ProposalDatabase {
     engine: string;

package/dist/analysis.js.map

@@ -1 +1 @@
-{"version":3,"file":"analysis.js","sourceRoot":"","sources":["../src/analysis.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AAoLlD,QAAA,eAAe,GAC1B,IAAA,kCAAiB,GAEd,CAAC;AAMO,QAAA,WAAW,GACtB,IAAA,kCAAiB,GAAoD,CAAC;AAc3D,QAAA,UAAU,GACrB,IAAA,kCAAiB,GAEd,CAAC"}
+{"version":3,"file":"analysis.js","sourceRoot":"","sources":["../src/analysis.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AAyMlD,QAAA,eAAe,GAC1B,IAAA,kCAAiB,GAEd,CAAC;AAMO,QAAA,WAAW,GACtB,IAAA,kCAAiB,GAAoD,CAAC;AAc3D,QAAA,UAAU,GACrB,IAAA,kCAAiB,GAEd,CAAC"}

package/dist/catalog.d.ts

@@ -81,6 +81,12 @@ export interface BlockTypeDescriptor {
     shapeSource: ShapeSource;
     description?: string;
     controllerArg?: boolean;
+    initialChildren?: BlockInitialChild[];
+}
+export interface BlockInitialChild {
+    id: string;
+    type: string;
+    options: Record<string, unknown>;
 }
 export interface DataTypeDescriptor {
     id: string;

package/dist/project.d.ts

@@ -10,6 +10,7 @@ export interface ModuleEntryInput {
     env?: Record<string, string>;
     importOverrides?: ImportOverrideInput[];
     exportPriority?: Record<string, number>;
+    disabledExports?: string[];
 }
 export interface AddModuleStep {
     op: "AddModule";
@@ -26,15 +27,28 @@ export interface CreateLocalModuleStep {
     id: string;
     path: string;
     entry?: ModuleEntryInput;
+    connection?: string;
 }
-export type ProjectConfigStep = AddModuleStep | ConfigureModuleStep | CreateLocalModuleStep;
+export interface RemoveModuleStep {
+    op: "RemoveModule";
+    id: string;
+}
+export interface RemoveConnectionStep {
+    op: "RemoveConnection";
+    interface: string;
+    id: string;
+}
+export type ProjectConfigStep = AddModuleStep | ConfigureModuleStep | CreateLocalModuleStep | RemoveModuleStep | RemoveConnectionStep;
 export interface ProjectConfigOpts {
     dryRun?: boolean;
 }
+export interface CreateLocalModuleOpts extends ProjectConfigOpts {
+    connection?: string;
+}
 export interface ProjectConfigResult {
     files: string[];
 }
 export declare const ConfigureProject: (steps: ProjectConfigStep[], opts?: ProjectConfigOpts | undefined) => Promise<OpResult<ProjectConfigResult>>;
 export declare const AddModule: (id: string, entry: ModuleEntryInput, opts?: ProjectConfigOpts | undefined) => Promise<OpResult<ProjectConfigResult>>;
 export declare const ConfigureModule: (id: string, entry: ModuleEntryInput, opts?: ProjectConfigOpts | undefined) => Promise<OpResult<ProjectConfigResult>>;
-export declare const CreateLocalModule: (id: string, path: string, entry?: ModuleEntryInput | undefined, opts?: ProjectConfigOpts | undefined) => Promise<OpResult<ProjectConfigResult>>;
+export declare const CreateLocalModule: (id: string, path: string, entry?: ModuleEntryInput | undefined, opts?: CreateLocalModuleOpts | undefined) => Promise<OpResult<ProjectConfigResult>>;

package/dist/project.js.map

@@ -1 +1 @@
-{"version":3,"file":"project.js","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AA8ElD,QAAA,gBAAgB,GAC3B,IAAA,kCAAiB,GAKd,CAAC;AAGO,QAAA,SAAS,GACpB,IAAA,kCAAiB,GAMd,CAAC;AAGO,QAAA,eAAe,GAC1B,IAAA,kCAAiB,GAMd,CAAC;AAGO,QAAA,iBAAiB,GAC5B,IAAA,kCAAiB,GAOd,CAAC"}
+{"version":3,"file":"project.js","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AA6GlD,QAAA,gBAAgB,GAC3B,IAAA,kCAAiB,GAKd,CAAC;AAGO,QAAA,SAAS,GACpB,IAAA,kCAAiB,GAMd,CAAC;AAGO,QAAA,eAAe,GAC1B,IAAA,kCAAiB,GAMd,CAAC;AAGO,QAAA,iBAAiB,GAC5B,IAAA,kCAAiB,GAOd,CAAC"}

package/dist/queries.js.map

@@ -1 +1 @@
-{"version":3,"file":"queries.js","sourceRoot":"","sources":["../src/queries.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AA0MlD,QAAA,kBAAkB,GAC7B,IAAA,kCAAiB,GAEd,CAAC;AAEO,QAAA,QAAQ,GACnB,IAAA,kCAAiB,GAMd,CAAC;AAEO,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAMd,CAAC;AAEO,QAAA,WAAW,GACtB,IAAA,kCAAiB,GAEd,CAAC"}
+{"version":3,"file":"queries.js","sourceRoot":"","sources":["../src/queries.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AA2MlD,QAAA,kBAAkB,GAC7B,IAAA,kCAAiB,GAEd,CAAC;AAEO,QAAA,QAAQ,GACnB,IAAA,kCAAiB,GAMd,CAAC;AAEO,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAMd,CAAC;AAEO,QAAA,WAAW,GACtB,IAAA,kCAAiB,GAEd,CAAC"}

package/dist/results.d.ts

@@ -14,7 +14,7 @@ export interface TypecheckError {
     message: string;
 }
 export interface OpWarning {
-    code: "query_opaque" | "query_kept" | "index_clamped" | "datatype_fallback" | "data_not_dropped" | "route_changed" | "data_kept" | "page_not_written" | "relation_missing";
+    code: "query_opaque" | "query_kept" | "index_clamped" | "datatype_fallback" | "data_not_dropped" | "route_changed" | "data_kept" | "page_not_written" | "relation_missing" | "module_not_loaded";
     message: string;
 }
 export type DuplicateScope = "page" | "siblings" | "category" | "resource" | "query" | "module";

package/docs/11.external-databases.md

@@ -2,9 +2,9 @@
 
 ## Overview
 
-A DMS project can show pages over a database it does not own: a client's PostgreSQL, read and written live through a postgres module in external mode. The builder takes such a database in four moves, each an operation:
+A DMS project can show pages over a database it does not own: a client's PostgreSQL, MongoDB or RethinkDB, read and written live through that engine's module (`@antelopejs/postgres`, `@antelopejs/mongodb`, `@antelopejs/rethinkdb`) in external mode. The builder takes such a database in four moves, each an operation:
 
-1. **Wire it** into `antelope.config.ts` with `ConfigureProject`: the provider module, a local module for its tables, and the builder's catalog connection.
+1. **Wire it** into `antelope.config.ts` with `ConfigureProject`: the provider module, a local module for its tables, the builder's catalog connection, and the DMS module's pin to the project's own database.
 2. **Analyse it** with `AnalyseDatabase`, which reads the catalog and proposes a mapping by fixed rules. It writes nothing.
 3. **Decide** the proposal: a person in the builder's *Database* workspace, or an assistant through these operations.
 4. **Map it** with `MapResources`, which writes table classes, controllers and TableView pages into the module bound to the database.
@@ -18,11 +18,23 @@ The builder reaches the database through `@antelopejs/interface-database-catalog
 | Step | Writes |
 | --- | --- |
 | `AddModule` | a module entry, refusing an id that exists |
-| `ConfigureModule` | merges config, `importOverrides` (pins and connection ids), `exportPriority` and env variable names into an entry |
-| `CreateLocalModule` | scaffolds a local module and adds its entry |
+| `ConfigureModule` | merges config, `importOverrides` (pins and connection ids), `exportPriority`, `disabledExports` and env variable names into an entry |
+| `CreateLocalModule` | scaffolds a local module and adds its entry; with `connection`, its record names that connection |
+| `RemoveModule` | removes an entry and the `envOverrides` entries supplying its config, refusing one another module still reads through; its files stay |
+| `RemoveConnection` | removes a named connection to an interface from every module's `importOverrides` |
 
 `env` takes variable names, never values: each is added to `envOverrides`, and to `.env.example` when the project has one.
 
+The provider's entry depends on its engine:
+
+| Engine | Package | `env` | `disabledExports` |
+| --- | --- | --- | --- |
+| PostgreSQL | `@antelopejs/postgres` | `url` | none |
+| MongoDB | `@antelopejs/mongodb` | `url` and `database` | `@antelopejs/interface-mongodb` |
+| RethinkDB | `@antelopejs/rethinkdb` | `url`, the database as its path | `@antelopejs/interface-rethinkdb` |
+
+`disabledExports` keeps core from ever offering the external instance's raw client, so a module that needs the DMS's own MongoDB or RethinkDB client never gets the client's database instead.
+
 ```typescript
 import { ConfigureProject } from "@antelopejs/interface-dms-builder";
 
@@ -36,20 +48,22 @@ const result = await ConfigureProject([
       source: { type: "package", package: "@antelopejs/postgres", version: "^0.2.0" },
       config: { mode: "external", statementTimeoutMs: 30000 },
       env: { url: "ERP_DATABASE_URL" },
+      exportPriority: { "@antelopejs/interface-database": -1 },
     },
   },
   {
     op: "CreateLocalModule",
     id: "erp-tables",
     path: "modules/erp-tables",
+    connection: "erp",
     entry: {
       importOverrides: [{ interface: "@antelopejs/interface-database", source: "postgres-erp" }],
     },
   },
   {
     op: "ConfigureModule",
-    id: "mongodb",
-    entry: { exportPriority: { "@antelopejs/interface-database": 1 } },
+    id: "dms",
+    entry: { importOverrides: [{ interface: "@antelopejs/interface-database", source: "mongodb" }] },
   },
   {
     op: "ConfigureModule",
@@ -59,8 +73,21 @@ const result = await ConfigureProject([
 ]);
 ```
 
+- The provider's `exportPriority` of `-1` keeps the project's own database the default for every module that does not pin `interface-database`.
+- The tables module pins `interface-database` to the provider, and uses the DMS. Core passes that pin on to the DMS, which every other module reaches with the default, so the DMS pins the project's own database to settle it. A DMS that already pins `interface-database` needs nothing more.
+
 The connection exists once the project restarts with the variable set.
 
+### Remove a Connection
+
+Removing a connection takes its catalog connections and its tables module out of the configuration, with `RemoveConnection` and `RemoveModule`. The tables module's folder is deleted with it. The database itself is untouched.
+
+The tables module is the one whose `dmsBuilder.database` record names the connection, which `CreateLocalModule` writes with `connection` (the single-step `CreateLocalModule` takes it in its options). Another module that reads through the provider is never removed or deleted.
+
+The provider goes too, with the variables that supply its configuration in `envOverrides`, `.env` and `.env.example`, only when it was added for this connection alone: its `exportPriority` for `@antelopejs/interface-database` is below the project's own database, and no module or connection the removal leaves names it. Otherwise it stays, since it may be the project's own database.
+
+A removal is all or nothing: the folders are moved aside and `.env` is edited first, and both are put back when the configuration cannot be written.
+
 ## Analyse a Database
 
 `AnalyseDatabase({ connection, module, schemas? })` starts a job and answers it at once: profiling a database takes a while. `GetAnalysis(id)` answers the job's `progress` while it runs, then its `proposal`, or its `error`.
@@ -100,18 +127,27 @@ A **fact** follows from the catalog with no judgement. A **default** is a judgem
 | R2 | no key | stats only: table class and model, no page |
 | R3 | no rows | excluded |
 | R4 | a framework's or a migration tool's table | excluded |
-| R5 | keyed by its two foreign keys | stats only |
+| R5 | keyed by its two references | stats only |
 | R6 | keyed, with rows and a label | TableView |
 | R7 | keyed, no label, referenced | TableView labelled by its key, and a `label` question |
 | R8 | keyed, no label, not referenced, with a time axis | stats only |
 | R9 | anything else | a `purpose` question, nothing proposed |
 | L1, L2 | the label by name, then by order; titles from short comments, else from names | |
-| F1–F5 | columns no type reads and secrets left out; the first declaration; declared foreign keys and references found whole as relation columns | |
+| F1–F5 | columns no type reads and secrets left out; the first declaration; references the database declares, and references found whole, as relation columns | |
 | W1 | every TableView | read-only |
 
 Each field also carries the declarations its column `accepts`, and its profile's aggregates: traits, nulls, distinct values, range and categories. Never a row.
 
-What the rules could not decide is in `open`, each item with its options and what the proposal holds meanwhile. A `purpose` item carries the `resource` it would map, should the answer be to map it.
+Each resource also carries its `rows`, counted by the profile or estimated, when either is known.
+
+What the rules could not decide is in `open`, each item with its options and what the proposal holds meanwhile:
+
+- A `label` item offers every column a field reads, the key among them.
+- A `reference` item offers a plain column, the target its values were found in, and every TableView whose single-column key accepts the column.
+- A `purpose` item carries the `resource` it would map, should the answer be to map it, and in its own `open` the questions that resource leaves: they are asked only once the answer maps it.
+- A `field-type` item asks which declaration reads a field of several native types.
+
+A document database declares no field types, so its catalog reads them from a sample. When no type covers enough of a field's values (`int 60% | string 40%`), the field is left out and a `field-type` item asks which declaration reads it: its options are a declaration per type seen, and leaving it out. The `_id` of a collection without a key is never declared, so it is left out and asks nothing. `MapResources` accepts the declaration it answers. MongoDB and RethinkDB declare no references either, so F5 finds them all.
 
 ## Map Relations
 
@@ -133,14 +169,23 @@ const result = await MapResources({
       fields: [{ column: "name", searchable: true }, { column: "segment", filterable: true }],
     },
   ],
-  excluded: [{ relation: "erp.audit_log", reason: "a log" }],
+  excluded: [{ relation: "erp.schema_migrations", reason: "a framework's or a migration tool's table" }],
 });
 ```
 
-- **Names are the database's own.** `_id` is declared only where the relation has a key, and nothing creates or alters a table.
+- **Names are the database's own.** `_id` is declared only where the relation has a key, and nothing creates or alters a table. A MongoDB collection's key is `_id` itself, which is declared once.
 - **Relation columns** point at a relation of the batch, or one the module mapped before, by its single-column key.
-- **Mapping again** a relation already mapped rewrites it from the new choices. Its page is created, kept or removed as `tableView` says.
-- **`excluded`** is recorded in the module's `package.json`, so the next analysis does not propose those relations. Mapping one later removes it from the record.
+- **Mapping again** a relation already mapped rewrites it from the new choices. Its page is created, kept or removed as `tableView` says, and takes the new `title`. The module's relation columns pointing at it take its new `label`.
+- **The module's `package.json`** records the connection and the `excluded` tables with their reasons, so the next analysis does not propose those tables. Mapping one later removes it from the record:
+
+  ```json
+  "dmsBuilder": {
+    "database": {
+      "connection": "erp",
+      "excludedTables": { "erp.schema_migrations": "a framework's or a migration tool's table" }
+    }
+  }
+  ```
 - **In a mapped module**, `CreateResource` and `AddField` are refused, since its tables are the database's. `DeleteResource` keeps the client's rows and warns `data_kept`.
 
 ## Next Steps

package/docs/3.catalog.md

@@ -42,6 +42,7 @@ The catalog is cached. `RefreshSourceIndex` with no scope drops that cache; see
 | `shapeSource` | `ShapeSource` | How the emit shape was determined. |
 | `description` | `string` | A human-readable description of the block. |
 | `controllerArg` | `boolean` | `true` when the factory takes a leading controller-class argument before its options object. |
+| `initialChildren` | `BlockInitialChild[]` | The children a new block of this type starts with, as the DMS's own helper places them in code (a `PageToolbar`'s `LiveToggle` and `PeriodSelector`, with the options of `pageToolbar()`). Each has an `id` (the child id roles name it by), a `type` (a catalog key) and its `options`. Absent for most types. |
 
 Only a `container` block can hold children, so it is the check to make before passing a block's path as `AddBlockInput.parent`.
 

package/docs/8.results-and-errors.md

@@ -39,7 +39,7 @@ Reads that use the envelope — `GetPageStructure`, `GetResourceStructure` — r
 | --- | --- | --- |
 | `path` | `string` | The file's absolute path. |
 | `kind` | `"create" \| "modify" \| "delete"` | What happened to the file. |
-| `diff` | `string` | A textual diff of the change. Empty for a deletion. |
+| `diff` | `string` | The change as unified diff hunks (`@@ -a,b +c,d @@`, then lines prefixed with a space, `-` or `+`), with no file headers. Empty for a deletion. |
 
 A single operation usually touches more than one file — creating a page writes the page file and rewrites the barrel that exports it; creating a resource writes three files and rewrites a barrel.
 

package/docs/tsconfig.json

@@ -4,7 +4,11 @@
     "rootDir": "..",
     "composite": false,
     "incremental": false,
-    "noEmit": true
+    "noEmit": true,
+    "paths": {
+      "@antelopejs/interface-dms-builder": ["../src/index.ts"],
+      "@antelopejs/interface-dms-builder/*": ["../src/*"]
+    }
   },
   "include": ["../src/**/*.ts", "**/*.ts"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/interface-dms-builder",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "AntelopeJS interface for the DMS builder: create and edit pages, blocks, resources and queries in a DMS project from another module.",
   "keywords": [
     "antelopejs",