Debian Codegraph @

packages/datagrid/src/jsonmodel.ts

raw
1 // Copyright (c) Jupyter Development Team.
2 // Distributed under the terms of the Modified BSD License.
3 /*-----------------------------------------------------------------------------
4 | Copyright (c) 2014-2019, PhosphorJS Contributors
5 |
6 | Distributed under the terms of the BSD 3-Clause License.
7 |
8 | The full license is in the file LICENSE, distributed with this software.
9 |----------------------------------------------------------------------------*/
10 import { ReadonlyJSONObject } from '@lumino/coreutils';
11
12 import { DataModel } from './datamodel';
13
14 /**
15 * A data model implementation for in-memory JSON data.
16 */
17 export class JSONModel extends DataModel {
18 /**
19 * Create a data model with static JSON data.
20 *
21 * @param options - The options for initializing the data model.
22 */
23 constructor(options: JSONModel.IOptions) {
24 super();
25 let split = Private.splitFields(options.schema);
26 this._data = options.data;
27 this._bodyFields = split.bodyFields;
28 this._headerFields = split.headerFields;
29 this._missingValues = Private.createMissingMap(options.schema);
30 }
31
32 /**
33 * Get the row count for a region in the data model.
34 *
35 * @param region - The row region of interest.
36 *
37 * @returns - The row count for the region.
38 */
39 rowCount(region: DataModel.RowRegion): number {
40 if (region === 'body') {
41 return this._data.length;
42 }
43 return 1; // TODO multiple column-header rows?
44 }
45
46 /**
47 * Get the column count for a region in the data model.
48 *
49 * @param region - The column region of interest.
50 *
51 * @returns - The column count for the region.
52 */
53 columnCount(region: DataModel.ColumnRegion): number {
54 if (region === 'body') {
55 return this._bodyFields.length;
56 }
57 return this._headerFields.length;
58 }
59
60 /**
61 * Get the data value for a cell in the data model.
62 *
63 * @param region - The cell region of interest.
64 *
65 * @param row - The row index of the cell of interest.
66 *
67 * @param column - The column index of the cell of interest.
68 *
69 * @returns - The data value for the specified cell.
70 *
71 * #### Notes
72 * A `missingValue` as defined by the schema is converted to `null`.
73 */
74 data(region: DataModel.CellRegion, row: number, column: number): any {
75 // Set up the field and value variables.
76 let field: JSONModel.Field;
77 let value: any;
78
79 // Look up the field and value for the region.
80 switch (region) {
81 case 'body':
82 field = this._bodyFields[column];
83 value = this._data[row][field.name];
84 break;
85 case 'column-header':
86 field = this._bodyFields[column];
87 value = field.title || field.name;
88 break;
89 case 'row-header':
90 field = this._headerFields[column];
91 value = this._data[row][field.name];
92 break;
93 case 'corner-header':
94 field = this._headerFields[column];
95 value = field.title || field.name;
96 break;
97 default:
98 throw 'unreachable';
99 }
100
101 // Test whether the value is a missing value.
102 let missing =
103 this._missingValues !== null &&
104 typeof value === 'string' &&
105 this._missingValues[value] === true;
106
107 // Return the final value.
108 return missing ? null : value;
109 }
110
111 /**
112 * Get the metadata for a cell in the data model.
113 *
114 * @param region - The cell region of interest.
115 *
116 * @param row - The row index of the cell of of interest.
117 *
118 * @param column - The column index of the cell of interest.
119 *
120 * @returns The metadata for the cell.
121 */
122 metadata(
123 region: DataModel.CellRegion,
124 row: number,
125 column: number
126 ): DataModel.Metadata {
127 if (region === 'body' || region === 'column-header') {
128 return this._bodyFields[column];
129 }
130 return this._headerFields[column];
131 }
132
133 private _data: JSONModel.DataSource;
134 private _bodyFields: JSONModel.Field[];
135 private _headerFields: JSONModel.Field[];
136 private _missingValues: Private.MissingValuesMap | null;
137 }
138
139 /**
140 * The namespace for the `JSONModel` class statics.
141 */
142 export namespace JSONModel {
143 /**
144 * An object which describes a column of data in the model.
145 *
146 * #### Notes
147 * This is based on the JSON Table Schema specification:
148 * https://specs.frictionlessdata.io/table-schema/
149 */
150 export type Field = {
151 /**
152 * The name of the column.
153 *
154 * This is used as the key to extract a value from a data record.
155 * It is also used as the column header label, unless the `title`
156 * property is provided.
157 */
158 readonly name: string;
159
160 /**
161 * The type of data held in the column.
162 */
163 readonly type?: string;
164
165 /**
166 * The format of the data in the column.
167 */
168 readonly format?: string;
169
170 /**
171 * The human readable name for the column.
172 *
173 * This is used as the label for the column header.
174 */
175 readonly title?: string;
176
177 // TODO want/need support for any these?
178 // description?: string;
179 // constraints?: IConstraints;
180 // rdfType?: string;
181 };
182
183 /**
184 * An object when specifies the schema for a data model.
185 *
186 * #### Notes
187 * This is based on the JSON Table Schema specification:
188 * https://specs.frictionlessdata.io/table-schema/
189 */
190 export type Schema = {
191 /**
192 * The fields which describe the data model columns.
193 *
194 * Primary key fields are rendered as row header columns.
195 */
196 readonly fields: Field[];
197
198 /**
199 * The values to treat as "missing" data.
200 *
201 * Missing values are automatically converted to `null`.
202 */
203 readonly missingValues?: string[];
204
205 /**
206 * The field names which act as primary keys.
207 *
208 * Primary key fields are rendered as row header columns.
209 */
210 readonly primaryKey?: string | string[];
211
212 // TODO want/need support for this?
213 // foreignKeys?: IForeignKey[];
214 };
215
216 /**
217 * A type alias for a data source for a JSON data model.
218 *
219 * A data source is an array of JSON object records which represent
220 * the rows of the table. The keys of the records correspond to the
221 * field names of the columns.
222 */
223 export type DataSource = ReadonlyArray<ReadonlyJSONObject>;
224
225 /**
226 * An options object for initializing a JSON data model.
227 */
228 export interface IOptions {
229 /**
230 * The schema for the for the data model.
231 *
232 * The schema should be treated as an immutable object.
233 */
234 schema: Schema;
235
236 /**
237 * The data source for the data model.
238 *
239 * The data model takes full ownership of the data source.
240 */
241 data: DataSource;
242 }
243 }
244
245 /**
246 * The namespace for the module implementation details.
247 */
248 namespace Private {
249 /**
250 * An object which holds the results of splitting schema fields.
251 */
252 export type SplitFieldsResult = {
253 /**
254 * The non-primary key fields to use for the grid body.
255 */
256 bodyFields: JSONModel.Field[];
257
258 /**
259 * The primary key fields to use for the grid headers.
260 */
261 headerFields: JSONModel.Field[];
262 };
263
264 /**
265 * Split the schema fields into header and body fields.
266 */
267 export function splitFields(schema: JSONModel.Schema): SplitFieldsResult {
268 // Normalize the primary keys.
269 let primaryKeys: string[];
270 if (schema.primaryKey === undefined) {
271 primaryKeys = [];
272 } else if (typeof schema.primaryKey === 'string') {
273 primaryKeys = [schema.primaryKey];
274 } else {
275 primaryKeys = schema.primaryKey;
276 }
277
278 // Separate the fields for the body and header.
279 let bodyFields: JSONModel.Field[] = [];
280 let headerFields: JSONModel.Field[] = [];
281 for (let field of schema.fields) {
282 if (primaryKeys.indexOf(field.name) === -1) {
283 bodyFields.push(field);
284 } else {
285 headerFields.push(field);
286 }
287 }
288
289 // Return the separated fields.
290 return { bodyFields, headerFields };
291 }
292
293 /**
294 * A type alias for a missing value map.
295 */
296 export type MissingValuesMap = { [key: string]: boolean };
297
298 /**
299 * Create a missing values map for a schema.
300 *
301 * This returns `null` if there are no missing values.
302 */
303 export function createMissingMap(
304 schema: JSONModel.Schema
305 ): MissingValuesMap | null {
306 // Bail early if there are no missing values.
307 if (!schema.missingValues || schema.missingValues.length === 0) {
308 return null;
309 }
310
311 // Collect the missing values into a map.
312 let result: MissingValuesMap = Object.create(null);
313 for (let value of schema.missingValues) {
314 result[value] = true;
315 }
316
317 // Return the populated map.
318 return result;
319 }
320 }