src/data/helper/SeriesDataSchema.ts - echarts - Git at Google

 /*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */

 import { createHashMap, HashMap, isObject, retrieve2 } from 'zrender/src/core/util';
 import { makeInner } from '../../util/model';
 import {
     DimensionDefinition, DimensionDefinitionLoose, DimensionIndex, DimensionName, DimensionType
 } from '../../util/types';
 import { DataStoreDimensionDefine } from '../DataStore';
 import OrdinalMeta from '../OrdinalMeta';
 import SeriesDimensionDefine from '../SeriesDimensionDefine';
 import { shouldRetrieveDataByName, Source } from '../Source';

 const inner = makeInner<{
     dimNameMap: HashMap<DimensionIndex, DimensionName>;
 }, Source>();

 const dimTypeShort = {
     float: 'f', int: 'i', ordinal: 'o', number: 'n', time: 't'
 } as const;

 /**
  * Represents the dimension requirement of a series.
  *
  * NOTICE:
  * When there are too many dimensions in dataset and many series, only the used dimensions
  * (i.e., used by coord sys and declared in `series.encode`) are add to `dimensionDefineList`.
  * But users may query data by other unused dimension names.
  * In this case, users can only query data if and only if they have defined dimension names
  * via ec option, so we provide `getDimensionIndexFromSource`, which only query them from
  * `source` dimensions.
  */
 export class SeriesDataSchema {

     /**
      * When there are too many dimensions, `dimensionDefineList` might only contain
      * used dimensions.
      *
      * CAUTION:
      * Should have been sorted by `storeDimIndex` asc.
      *
      * PENDING:
      * The item can still be modified outsite.
      * But MUST NOT add/remove item of this array.
      */
     readonly dimensions: SeriesDimensionDefine[];

     readonly source: Source;

     private _fullDimCount: number;
     private _dimNameMap: ReturnType<typeof inner>['dimNameMap'];
     private _dimOmitted: boolean;

     constructor(opt: {
         source: Source,
         dimensions: SeriesDimensionDefine[],
         fullDimensionCount: number,
         dimensionOmitted: boolean
     }) {
         this.dimensions = opt.dimensions;
         this._dimOmitted = opt.dimensionOmitted;
         this.source = opt.source;
         this._fullDimCount = opt.fullDimensionCount;

         this._updateDimOmitted(opt.dimensionOmitted);
     }

     isDimensionOmitted(): boolean {
         return this._dimOmitted;
     }

     private _updateDimOmitted(dimensionOmitted: boolean): void {
         this._dimOmitted = dimensionOmitted;
         if (!dimensionOmitted) {
             return;
         }
         if (!this._dimNameMap) {
             this._dimNameMap = ensureSourceDimNameMap(this.source);
         }
     }

     /**
      * @caution Can only be used when `dimensionOmitted: true`.
      *
      * Get index by user defined dimension name (i.e., not internal generate name).
      * That is, get index from `dimensionsDefine`.
      * If no `dimensionsDefine`, or no name get, return -1.
      */
     getSourceDimensionIndex(dimName: DimensionName): DimensionIndex {
         return retrieve2(this._dimNameMap.get(dimName), -1);
     }

     /**
      * @caution Can only be used when `dimensionOmitted: true`.
      *
      * Notice: may return `null`/`undefined` if user not specify dimension names.
      */
     getSourceDimension(dimIndex: DimensionIndex): DimensionDefinition {
         const dimensionsDefine = this.source.dimensionsDefine;
         if (dimensionsDefine) {
             return dimensionsDefine[dimIndex];
         }
     }

     makeStoreSchema(): {
         dimensions: DataStoreDimensionDefine[];
         hash: string
     } {
         const dimCount = this._fullDimCount;
         const willRetrieveDataByName = shouldRetrieveDataByName(this.source);
         const makeHashStrict = !shouldOmitUnusedDimensions(dimCount);

         // If source don't have dimensions or series don't omit unsed dimensions.
         // Generate from seriesDimList directly
         let dimHash = '';
         const dims: DataStoreDimensionDefine[] = [];

         for (let fullDimIdx = 0, seriesDimIdx = 0; fullDimIdx < dimCount; fullDimIdx++) {
             let property: string;
             let type: DimensionType;
             let ordinalMeta: OrdinalMeta;

             const seriesDimDef = this.dimensions[seriesDimIdx];
             // The list has been sorted by `storeDimIndex` asc.
             if (seriesDimDef && seriesDimDef.storeDimIndex === fullDimIdx) {
                 property = willRetrieveDataByName ? seriesDimDef.name : null;
                 type = seriesDimDef.type;
                 ordinalMeta = seriesDimDef.ordinalMeta;

                 seriesDimIdx++;
             }
             else {
                 const sourceDimDef = this.getSourceDimension(fullDimIdx);
                 if (sourceDimDef) {
                     property = willRetrieveDataByName ? sourceDimDef.name : null;
                     type = sourceDimDef.type;
                 }
             }

             dims.push({ property, type, ordinalMeta });

             // If retrieving data by index,
             //   use <index, type, ordinalMeta> to determine whether data can be shared.
             //   (Because in this case there might be no dimension name defined in dataset, but indices always exists).
             //   (Indices are always 0, 1, 2, ..., so we can ignore them to shorten the hash).
             // Otherwise if retrieving data by property name (like `data: [{aa: 123, bb: 765}, ...]`),
             //   use <property, type, ordinalMeta> in hash.
             if (willRetrieveDataByName
                 && property != null
                 // For data stack, we have make sure each series has its own dim on this store.
                 // So we do not add property to hash to make sure they can share this store.
                 && (!seriesDimDef || !seriesDimDef.isCalculationCoord)
             ) {
                 dimHash += (makeHashStrict
                     // Use escape character '`' in case that property name contains '$'.
                     ? property.replace(/\`/g, '`1').replace(/\$/g, '`2')
                     // For better performance, when there are large dimensions, tolerant this defects that hardly meet.
                     : property
                 );
             }
             dimHash += '$';
             dimHash += dimTypeShort[type] || 'f';

             if (ordinalMeta) {
                 dimHash += ordinalMeta.uid;
             }

             dimHash += '$';
         }

         // Source from endpoint(usually series) will be read differently
         // when seriesLayoutBy or startIndex(which is affected by sourceHeader) are different.
         // So we use this three props as key.
         const source = this.source;
         const hash = [
             source.seriesLayoutBy,
             source.startIndex,
             dimHash
         ].join('$$');

         return {
             dimensions: dims,
             hash: hash
         };
     }

     makeOutputDimensionNames(): DimensionName[] {
         const result = [] as DimensionName[];

         for (let fullDimIdx = 0, seriesDimIdx = 0; fullDimIdx < this._fullDimCount; fullDimIdx++) {
             let name: DimensionName;
             const seriesDimDef = this.dimensions[seriesDimIdx];
             // The list has been sorted by `storeDimIndex` asc.
             if (seriesDimDef && seriesDimDef.storeDimIndex === fullDimIdx) {
                 if (!seriesDimDef.isCalculationCoord) {
                     name = seriesDimDef.name;
                 }
                 seriesDimIdx++;
             }
             else {
                 const sourceDimDef = this.getSourceDimension(fullDimIdx);
                 if (sourceDimDef) {
                     name = sourceDimDef.name;
                 }
             }
             result.push(name);
         }

         return result;
     }

     appendCalculationDimension(dimDef: SeriesDimensionDefine): void {
         this.dimensions.push(dimDef);
         dimDef.isCalculationCoord = true;
         this._fullDimCount++;
         // If append dimension on a data store, consider the store
         // might be shared by different series, series dimensions not
         // really map to store dimensions.
         this._updateDimOmitted(true);
     }
 }

 export function isSeriesDataSchema(
     schema: any
 ): schema is SeriesDataSchema {
     return schema instanceof SeriesDataSchema;
 }


 export function createDimNameMap(dimsDef: DimensionDefinitionLoose[]): HashMap<DimensionIndex, DimensionName> {
     const dataDimNameMap = createHashMap<DimensionIndex, DimensionName>();
     for (let i = 0; i < (dimsDef || []).length; i++) {
         const dimDefItemRaw = dimsDef[i];
         const userDimName = isObject(dimDefItemRaw) ? dimDefItemRaw.name : dimDefItemRaw;
         if (userDimName != null && dataDimNameMap.get(userDimName) == null) {
             dataDimNameMap.set(userDimName, i);
         }
     }
     return dataDimNameMap;
 }

 export function ensureSourceDimNameMap(source: Source): HashMap<DimensionIndex, DimensionName> {
     const innerSource = inner(source);
     return innerSource.dimNameMap || (
         innerSource.dimNameMap = createDimNameMap(source.dimensionsDefine)
     );
 }

 export function shouldOmitUnusedDimensions(dimCount: number): boolean {
     return dimCount > 30;
 }
	/*
	* Licensed to the Apache Software Foundation (ASF) under one
	* or more contributor license agreements. See the NOTICE file
	* distributed with this work for additional information
	* regarding copyright ownership. The ASF licenses this file
	* to you under the Apache License, Version 2.0 (the
	* "License"); you may not use this file except in compliance
	* with the License. You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing,
	* software distributed under the License is distributed on an
	* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	* KIND, either express or implied. See the License for the
	* specific language governing permissions and limitations
	* under the License.
	*/

	import { createHashMap, HashMap, isObject, retrieve2 } from 'zrender/src/core/util';
	import { makeInner } from '../../util/model';
	import {
	DimensionDefinition, DimensionDefinitionLoose, DimensionIndex, DimensionName, DimensionType
	} from '../../util/types';
	import { DataStoreDimensionDefine } from '../DataStore';
	import OrdinalMeta from '../OrdinalMeta';
	import SeriesDimensionDefine from '../SeriesDimensionDefine';
	import { shouldRetrieveDataByName, Source } from '../Source';

	const inner = makeInner<{
	dimNameMap: HashMap<DimensionIndex, DimensionName>;
	}, Source>();

	const dimTypeShort = {
	float: 'f', int: 'i', ordinal: 'o', number: 'n', time: 't'
	} as const;

	/**
	* Represents the dimension requirement of a series.
	*
	* NOTICE:
	* When there are too many dimensions in dataset and many series, only the used dimensions
	* (i.e., used by coord sys and declared in `series.encode`) are add to `dimensionDefineList`.
	* But users may query data by other unused dimension names.
	* In this case, users can only query data if and only if they have defined dimension names
	* via ec option, so we provide `getDimensionIndexFromSource`, which only query them from
	* `source` dimensions.
	*/
	export class SeriesDataSchema {

	/**
	* When there are too many dimensions, `dimensionDefineList` might only contain
	* used dimensions.
	*
	* CAUTION:
	* Should have been sorted by `storeDimIndex` asc.
	*
	* PENDING:
	* The item can still be modified outsite.
	* But MUST NOT add/remove item of this array.
	*/
	readonly dimensions: SeriesDimensionDefine[];

	readonly source: Source;

	private _fullDimCount: number;
	private _dimNameMap: ReturnType<typeof inner>['dimNameMap'];
	private _dimOmitted: boolean;

	constructor(opt: {
	source: Source,
	dimensions: SeriesDimensionDefine[],
	fullDimensionCount: number,
	dimensionOmitted: boolean
	}) {
	this.dimensions = opt.dimensions;
	this._dimOmitted = opt.dimensionOmitted;
	this.source = opt.source;
	this._fullDimCount = opt.fullDimensionCount;

	this._updateDimOmitted(opt.dimensionOmitted);
	}

	isDimensionOmitted(): boolean {
	return this._dimOmitted;
	}

	private _updateDimOmitted(dimensionOmitted: boolean): void {
	this._dimOmitted = dimensionOmitted;
	if (!dimensionOmitted) {
	return;
	}
	if (!this._dimNameMap) {
	this._dimNameMap = ensureSourceDimNameMap(this.source);
	}
	}

	/**
	* @caution Can only be used when `dimensionOmitted: true`.
	*
	* Get index by user defined dimension name (i.e., not internal generate name).
	* That is, get index from `dimensionsDefine`.
	* If no `dimensionsDefine`, or no name get, return -1.
	*/
	getSourceDimensionIndex(dimName: DimensionName): DimensionIndex {
	return retrieve2(this._dimNameMap.get(dimName), -1);
	}

	/**
	* @caution Can only be used when `dimensionOmitted: true`.
	*
	* Notice: may return `null`/`undefined` if user not specify dimension names.
	*/
	getSourceDimension(dimIndex: DimensionIndex): DimensionDefinition {
	const dimensionsDefine = this.source.dimensionsDefine;
	if (dimensionsDefine) {
	return dimensionsDefine[dimIndex];
	}
	}

	makeStoreSchema(): {
	dimensions: DataStoreDimensionDefine[];
	hash: string
	} {
	const dimCount = this._fullDimCount;
	const willRetrieveDataByName = shouldRetrieveDataByName(this.source);
	const makeHashStrict = !shouldOmitUnusedDimensions(dimCount);

	// If source don't have dimensions or series don't omit unsed dimensions.
	// Generate from seriesDimList directly
	let dimHash = '';
	const dims: DataStoreDimensionDefine[] = [];

	for (let fullDimIdx = 0, seriesDimIdx = 0; fullDimIdx < dimCount; fullDimIdx++) {
	let property: string;
	let type: DimensionType;
	let ordinalMeta: OrdinalMeta;

	const seriesDimDef = this.dimensions[seriesDimIdx];
	// The list has been sorted by `storeDimIndex` asc.
	if (seriesDimDef && seriesDimDef.storeDimIndex === fullDimIdx) {
	property = willRetrieveDataByName ? seriesDimDef.name : null;
	type = seriesDimDef.type;
	ordinalMeta = seriesDimDef.ordinalMeta;

	seriesDimIdx++;
	}
	else {
	const sourceDimDef = this.getSourceDimension(fullDimIdx);
	if (sourceDimDef) {
	property = willRetrieveDataByName ? sourceDimDef.name : null;
	type = sourceDimDef.type;
	}
	}

	dims.push({ property, type, ordinalMeta });

	// If retrieving data by index,
	// use <index, type, ordinalMeta> to determine whether data can be shared.
	// (Because in this case there might be no dimension name defined in dataset, but indices always exists).
	// (Indices are always 0, 1, 2, ..., so we can ignore them to shorten the hash).
	// Otherwise if retrieving data by property name (like `data: [{aa: 123, bb: 765}, ...]`),
	// use <property, type, ordinalMeta> in hash.
	if (willRetrieveDataByName
	&& property != null
	// For data stack, we have make sure each series has its own dim on this store.
	// So we do not add property to hash to make sure they can share this store.
	&& (!seriesDimDef \|\| !seriesDimDef.isCalculationCoord)
	) {
	dimHash += (makeHashStrict
	// Use escape character '`' in case that property name contains '$'.
	? property.replace(/\`/g, '`1').replace(/\$/g, '`2')
	// For better performance, when there are large dimensions, tolerant this defects that hardly meet.
	: property
	);
	}
	dimHash += '$';
	dimHash += dimTypeShort[type] \|\| 'f';

	if (ordinalMeta) {
	dimHash += ordinalMeta.uid;
	}

	dimHash += '$';
	}

	// Source from endpoint(usually series) will be read differently
	// when seriesLayoutBy or startIndex(which is affected by sourceHeader) are different.
	// So we use this three props as key.
	const source = this.source;
	const hash = [
	source.seriesLayoutBy,
	source.startIndex,
	dimHash
	].join('$$');

	return {
	dimensions: dims,
	hash: hash
	};
	}

	makeOutputDimensionNames(): DimensionName[] {
	const result = [] as DimensionName[];

	for (let fullDimIdx = 0, seriesDimIdx = 0; fullDimIdx < this._fullDimCount; fullDimIdx++) {
	let name: DimensionName;
	const seriesDimDef = this.dimensions[seriesDimIdx];
	// The list has been sorted by `storeDimIndex` asc.
	if (seriesDimDef && seriesDimDef.storeDimIndex === fullDimIdx) {
	if (!seriesDimDef.isCalculationCoord) {
	name = seriesDimDef.name;
	}
	seriesDimIdx++;
	}
	else {
	const sourceDimDef = this.getSourceDimension(fullDimIdx);
	if (sourceDimDef) {
	name = sourceDimDef.name;
	}
	}
	result.push(name);
	}

	return result;
	}

	appendCalculationDimension(dimDef: SeriesDimensionDefine): void {
	this.dimensions.push(dimDef);
	dimDef.isCalculationCoord = true;
	this._fullDimCount++;
	// If append dimension on a data store, consider the store
	// might be shared by different series, series dimensions not
	// really map to store dimensions.
	this._updateDimOmitted(true);
	}
	}

	export function isSeriesDataSchema(
	schema: any
	): schema is SeriesDataSchema {
	return schema instanceof SeriesDataSchema;
	}


	export function createDimNameMap(dimsDef: DimensionDefinitionLoose[]): HashMap<DimensionIndex, DimensionName> {
	const dataDimNameMap = createHashMap<DimensionIndex, DimensionName>();
	for (let i = 0; i < (dimsDef \|\| []).length; i++) {
	const dimDefItemRaw = dimsDef[i];
	const userDimName = isObject(dimDefItemRaw) ? dimDefItemRaw.name : dimDefItemRaw;
	if (userDimName != null && dataDimNameMap.get(userDimName) == null) {
	dataDimNameMap.set(userDimName, i);
	}
	}
	return dataDimNameMap;
	}

	export function ensureSourceDimNameMap(source: Source): HashMap<DimensionIndex, DimensionName> {
	const innerSource = inner(source);
	return innerSource.dimNameMap \|\| (
	innerSource.dimNameMap = createDimNameMap(source.dimensionsDefine)
	);
	}

	export function shouldOmitUnusedDimensions(dimCount: number): boolean {
	return dimCount > 30;
	}