@memorysmithapp/markdown-renderer 0.9.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,170 @@
1
+ /**
2
+ * The `table` block (§7.15, #137) and the query language its `where` is written in (§6.9).
3
+ *
4
+ * A block holds a question about a table of the notebook and never its rows: which table, which
5
+ * columns, which rows, in which order, how many to a page, and which column to sum. This module
6
+ * reads the question — the lines of the block, and the filter as a tree — and says what is wrong
7
+ * with it, alone or against the columns of the table the host keeps. It fetches nothing and knows
8
+ * no React, so `diagnose` runs it on a server as the page does in a browser.
9
+ *
10
+ * The query language is MemorySmith's search (§2), with what the specification adds for a table:
11
+ * a field is a column, a bare term looks in every text and list column, and an interval compares
12
+ * a number as well as a date.
13
+ */
14
+ /** The kind of a column (§5.9), which decides how a query matches it (§6.9). */
15
+ export type TableColumnKind = 'text' | 'number' | 'date' | 'boolean' | 'list';
16
+ export interface TableColumn {
17
+ /** The column's name as the table writes it, which is what a header shows. */
18
+ readonly name: string;
19
+ readonly kind: TableColumnKind;
20
+ }
21
+ /** What the host knows of a table it keeps: its columns, in the table's own order. */
22
+ export interface TableSchema {
23
+ readonly name: string;
24
+ readonly columns: readonly TableColumn[];
25
+ }
26
+ /** The codes a `table` block raises (§7.13). */
27
+ export type TableNoticeCode = 'table-unnamed' | 'table-key-unknown' | 'table-key-invalid' | 'table-column-unknown' | 'table-filter-invalid' | 'table-pending';
28
+ /** One mistake of a block: its code, the line of the block it is on (0 is the opening fence) and what it was about. */
29
+ export interface TableProblem {
30
+ readonly code: TableNoticeCode;
31
+ readonly line: number;
32
+ readonly detail?: string;
33
+ }
34
+ /** One column of `sort`, and its direction. */
35
+ export interface TableSortKey {
36
+ readonly column: string;
37
+ readonly descending: boolean;
38
+ }
39
+ /** A block as it was read: what each key said, and where each key was written. */
40
+ export interface TableBlock {
41
+ /** The table it names, trimmed and in NFC; `null` when it names none (§5.9). */
42
+ readonly table: string | null;
43
+ readonly columns: readonly string[] | null;
44
+ readonly where: QueryNode | null;
45
+ /** The filter as it was written, for a line that names it. */
46
+ readonly whereText: string | null;
47
+ readonly sort: readonly TableSortKey[] | null;
48
+ readonly page: number;
49
+ readonly total: string | null;
50
+ /** The mistakes that do not need the table, at most one a line. */
51
+ readonly problems: readonly TableProblem[];
52
+ /** The line of each key that was read, for the mistakes found against the table. */
53
+ readonly lines: Readonly<Partial<Record<TableKey, number>>>;
54
+ }
55
+ /** The six keys, in English in every notebook (§7.15). */
56
+ export declare const TABLE_KEYS: readonly ["table", "columns", "where", "sort", "page", "total"];
57
+ export type TableKey = (typeof TABLE_KEYS)[number];
58
+ /** Rows to a page when the block says nothing, and the most it may ask for. */
59
+ export declare const DEFAULT_PAGE = 25;
60
+ export declare const MAX_PAGE = 100;
61
+ /** Whether a fenced code block is a `table` block: its info string is the word `table` and nothing else. */
62
+ export declare function isTableBlock(lang: string | null | undefined, meta: string | null | undefined): boolean;
63
+ /**
64
+ * Text as a query compares it (§6.9): case folded and combining marks stripped. A character keeps
65
+ * its length where it can, as MemorySmith's search folds it.
66
+ */
67
+ export declare function fold(raw: string): string;
68
+ /** A table's name as it is compared (§5.9): in NFC, with case folded. */
69
+ export declare function tableKey(name: string): string;
70
+ /**
71
+ * Reads the lines of a block. `value` is the content of the fence, without the fences, one line of
72
+ * the block to each line of it.
73
+ */
74
+ export declare function readTableBlock(value: string): TableBlock;
75
+ /**
76
+ * The mistakes a block makes against the table it names: the ones it makes alone, then a pending
77
+ * table, a column the table does not have, a `total` that is not a drawn number, and a filter its
78
+ * columns cannot answer. `schema` is `undefined` when nothing is known of the notebook's tables,
79
+ * and `null` when the notebook keeps no table of that name. A line raises one mistake at most.
80
+ */
81
+ export declare function checkTableBlock(block: TableBlock, schema: TableSchema | null | undefined): TableProblem[];
82
+ export type Comparison = '>=' | '>' | '<=' | '<';
83
+ /** A query read into a tree. Fields and values are folded; a range keeps its two ends. */
84
+ export type QueryNode = {
85
+ readonly kind: 'term';
86
+ readonly field: string | null;
87
+ readonly value: string;
88
+ } | {
89
+ readonly kind: 'compare';
90
+ readonly field: string;
91
+ readonly op: Comparison;
92
+ readonly value: string;
93
+ } | {
94
+ readonly kind: 'range';
95
+ readonly field: string;
96
+ readonly from: string;
97
+ readonly to: string;
98
+ } | {
99
+ readonly kind: 'not';
100
+ readonly node: QueryNode;
101
+ } | {
102
+ readonly kind: 'and';
103
+ readonly nodes: readonly QueryNode[];
104
+ } | {
105
+ readonly kind: 'or';
106
+ readonly nodes: readonly QueryNode[];
107
+ };
108
+ /** A query that cannot be read, whatever it is asked of (§6.9). */
109
+ export declare class QuerySyntaxError extends Error {
110
+ }
111
+ /** Reads a query: `OR` binds loosest, then the implicit *and*, then `-`, then a term or a group. */
112
+ export declare function parseQuery(raw: string): QueryNode;
113
+ /** Every field a query names, folded, in the order it names them. */
114
+ export declare function fields(node: QueryNode): string[];
115
+ /**
116
+ * One value of a row. A number and a date travel as text — a number as its decimal digits, so a
117
+ * value of 38 digits is never rounded through a floating point, a date in ISO 8601 — a boolean as
118
+ * itself, a list as its items, and an empty value as `null`.
119
+ */
120
+ export type TableValue = string | boolean | readonly string[] | null;
121
+ /** A row, by the name of each column as the table writes it. A column it lacks is empty. */
122
+ export type TableRow = Readonly<Record<string, TableValue>>;
123
+ /** What a `table` block asks the host for (#138). */
124
+ export interface TableRequest {
125
+ /** The table, as the block names it: trimmed and in NFC, compared by the host with case folded (§5.9). */
126
+ readonly table: string;
127
+ /** The columns the block draws, as it wrote them, or `null` for every one. */
128
+ readonly columns: readonly string[] | null;
129
+ /** The filter as the block wrote it (§6.9), or `null` for every row. The host runs it. */
130
+ readonly where: string | null;
131
+ /** The order: the block's, or the reader's once they sort by a header; empty is insertion order. */
132
+ readonly sort: readonly TableSortKey[];
133
+ /** The page, from 1. */
134
+ readonly page: number;
135
+ /** Rows to a page, or `'all'` for every row the filter returns, which printing asks for. */
136
+ readonly size: number | 'all';
137
+ /** The column whose sum over the whole filter closes the table, or `null`. */
138
+ readonly total: string | null;
139
+ }
140
+ /** What the host answers for a table it keeps (#138). */
141
+ export interface TablePage {
142
+ /** The table's columns, in its own order, with their kinds. */
143
+ readonly schema: TableSchema;
144
+ /** The rows of the page asked for. */
145
+ readonly rows: readonly TableRow[];
146
+ /** How many rows the whole filter returns, which numbers the pages. */
147
+ readonly count: number;
148
+ /** The sum of `total` over the whole filter, as decimal digits, or `null` when none was asked. */
149
+ readonly total: string | null;
150
+ /** When the rows were read, in ISO 8601. */
151
+ readonly readAt: string;
152
+ }
153
+ /**
154
+ * Answers a request from a table held in memory, as `SPEC.md` §6.9 and §7.15 say a query is
155
+ * answered: the filter, the order, the page and the total. A host that keeps its tables elsewhere
156
+ * answers in its own store; this is the reference its answers can be compared with, and what the
157
+ * playground answers with. A filter that cannot be read throws `QuerySyntaxError`.
158
+ */
159
+ export declare function runTableQuery(table: {
160
+ readonly schema: TableSchema;
161
+ readonly rows: readonly TableRow[];
162
+ }, request: TableRequest, readAt?: string): TablePage;
163
+ /**
164
+ * The order of two values of one kind (§7.15): numbers as numbers, dates in ISO 8601, which orders
165
+ * as text, booleans `false` first, text and lists by their folded text. An empty value comes last
166
+ * in either direction.
167
+ */
168
+ export declare function compareValues(a: TableValue, b: TableValue, kind: TableColumnKind, descending?: boolean): number;
169
+ /** The exact sum of decimals, written in digits. */
170
+ export declare function sumDecimals(values: readonly string[]): string;