pict-section-recordset 1.0.0 → 1.0.2

package/source/providers/RecordSet-RecordProvider-Base.js

@@ -0,0 +1,217 @@
+
+const libPictProvider = require('pict-provider');
+
+/**
+ * Default configuration for the RecordSetProvider provider.
+ * @type {Record<string, any>}
+ */
+const _DefaultProviderConfiguration = {
+	ProviderIdentifier: 'Pict-RecordSetProvider',
+	AutoInitialize: true,
+	AutoInitializeOrdinal: 0,
+	AutoSolveWithApp: false,
+};
+
+/**
+ * @typedef {Object} RecordSetSearchRangeFacet
+ * @property {string} Field - The field to facet on. Only indexed fields can be faceted.
+ * @property {any} Start - The start of the range. (ex. 1900)
+ * @property {any} End - The end of the range. (ex. 2025)
+ * @property {any} Gap - The gap between range values. (ex. 25)
+ * TODO: Support auto-generating ranges based on the data at rest?
+ */
+
+/**
+ * @typedef {Object} RecordSetSearchFacetPayload
+ * @property {boolean} [ReturnRecords] - If false, search will return facets only, not records.
+ * @property {Array<string>} Fields - Requests to facet on all unique values of the given fields.
+ * @property {Array<RecordSetSearchRangeFacet>} Ranges - Requests to facet on given ranges of field values.
+ * TODO: support facet on custom query?
+ */
+
+/**
+ * @typedef {Object} RecordSetResult
+ * @property {Array<Record<string, any>>} Records - The records returned from the provider.
+ * @property {Record<string, Record<string, number>> & { ByRange?: Record<string, number> }} Facets - The facets returned from the provider.
+ */
+
+/**
+ * @typedef {Object} RecordSetFilter
+ * @property {string} [Entity] - The entity name. Can be used as an override to achieve LiteExtended, etc.
+ * @property {string} [FilterString] - A meadow endpoint style filter to apply.
+ * @property {number} [Offset] - The starting record number for pagination.
+ * @property {number} [PageSize] - The starting record number for pagination.
+ * @property {RecordSetSearchFacetPayload} [Facets] - The faceting config for the search.
+ */
+
+/**
+ * Base record set provider.
+ * @extends libPictProvider
+ */
+class RecordSetProviderBase extends libPictProvider
+{
+	/**
+	 * Creates an instance of RecordSetProvider.
+	 * @param {import('fable')} pFable - The Fable object.
+	 * @param {Record<string, any>} [pOptions] - Custom options for the provider.
+	 * @param {string} [pServiceHash] - The service hash.
+	 */
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		const tmpOptions = Object.assign({}, JSON.parse(JSON.stringify(_DefaultProviderConfiguration)), pOptions);
+
+		super(pFable, tmpOptions, pServiceHash);
+
+		/** @type {Record<string, any>} */
+		this.options;
+		/** @type {import('fable')} */
+		this.fable;
+		/** @type {import('pict')} */
+		this.pict;
+	}
+
+	/**
+	 * Get a record by its ID or GUID.
+	 *
+	 * @param {string|number} pIDOrGuid - The ID or GUID of the record.
+	 */
+	async getRecord(pIDOrGuid)
+	{
+		this.pict.log.info(`RecordSetProviderBase.getRecord(${pIDOrGuid})`);
+		return { };
+	}
+
+	/**
+	 * Get a record by its ID or GUID.
+	 *
+	 * @param {string|number} pGuid - The ID or GUID of the record.
+	 */
+	async getRecordByGUID(pGuid)
+	{
+		this.pict.log.info(`RecordSetProviderBase.getRecordByGUID(${pGuid})`);
+		return { };
+	}
+
+	/**
+	 * Read records from the provider.
+	 *
+	 * @param {RecordSetFilter} pOptions - Options for the read operation.
+	 * @return {Promise<RecordSetResult>} - The result of the read operation.
+	 */
+	async getRecords(pOptions)
+	{
+		this.pict.log.info(`RecordSetProviderBase.getRecords(${JSON.stringify(pOptions)})`);
+		return { Records: [], Facets: { } };
+	}
+
+	/**
+	 * Read records from the provider.
+	 *
+	 * @param {string} [pFilterString] - The filter string to apply.
+	 * @param {number} [pOffset] - The starting record number for pagination.
+	 * @param {number} [pPageSize] - The number of records to return.
+	 * @return {Promise<RecordSetResult>} - The result of the read operation.
+	 */
+	async getRecordsInline(pFilterString = '', pOffset = 0, pPageSize = 250)
+	{
+		this.pict.log.info(`RecordSetProviderBase.getRecordsInline(${pFilterString}, ${pOffset}, ${pPageSize})`);
+		return { Records: [], Facets: { } };
+	}
+
+	/**
+	 * Read records from the provider.
+	 *
+	 * @param {RecordSetFilter} pOptions - Options for the read operation.
+	 */
+	async getRecordSetCount(pOptions)
+	{
+		this.pict.log.info(`RecordSetProviderBase.getRecordSetCount(${JSON.stringify(pOptions)})`);
+		return { Count: 0 };
+	}
+
+	/**
+	 * Create a new record.
+	 *
+	 * @param {Record<string, any>} pRecord - The record to create.
+	 */
+	async createRecord(pRecord)
+	{
+		this.pict.log.info(`RecordSetProviderBase.createRecord(${JSON.stringify(pRecord)})`);
+		return pRecord;
+	}
+
+	/**
+	 * Update a record.
+	 *
+	 * @param {Record<string, any>} pRecord - The record to update.
+	 */
+	async updateRecord(pRecord)
+	{
+		this.pict.log.info(`RecordSetProviderBase.updateRecord(${JSON.stringify(pRecord)})`);
+		return pRecord;
+	}
+
+	/**
+	 * Delete a record.
+	 *
+	 * @param {Record<string, any>} pRecord - The record to delete.
+	 */
+	async deleteRecord(pRecord)
+	{
+		this.pict.log.info(`RecordSetProviderBase.deleteRecord(${JSON.stringify(pRecord)})`);
+	}
+
+	/**
+	 * Read a record.
+	 *
+	 * @param {string|number} pIDOrGuid - The ID or GUID of the record.
+	 */
+	async readRecord(pIDOrGuid)
+	{
+		this.pict.log.info(`RecordSetProviderBase.readRecord(${pIDOrGuid})`);
+		return { };
+	}
+
+	/**
+	 * Read records from the provider.
+	 *
+	 * @param {RecordSetFilter} pOptions - Options for the read operation.
+	 * @return {Promise<RecordSetResult>} - The result of the read operation.
+	 */
+	async readRecords(pOptions)
+	{
+		this.pict.log.info(`RecordSetProviderBase.readRecords(${JSON.stringify(pOptions)})`);
+		return { Records: [], Facets: { } };
+	}
+
+	/**
+	 * Clone a record.
+	 *
+	 * @param {Record<string, any>} pRecord - The record to clone.
+	 */
+	async cloneRecord(pRecord)
+	{
+		return this.createRecord(this.cleanRecord(pRecord));
+	}
+
+	/**
+	 * Remove any intrinsic identifiers from a record.
+	 *
+	 * @param {Record<string, any>} pRecord - The record to clean.
+	 */
+	cleanRecord(pRecord)
+	{
+		return pRecord;
+	}
+
+	/**
+	 * @return {Record<string, any>} The schema of the record.
+	 */
+	get recordSchema()
+	{
+		return { };
+	}
+}
+
+module.exports = RecordSetProviderBase;
+module.exports.default_configuration = _DefaultProviderConfiguration;

package/source/providers/RecordSet-RecordProvider-MeadowEndpoints.js

@@ -0,0 +1,339 @@
+
+const libRecordSetProviderBase = require('./RecordSet-RecordProvider-Base.js');
+
+/**
+ * @typedef {(error?: Error, result?: any) => void} RestClientCallback
+ *
+ * @typedef {import('./RecordSet-RecordProvider-Base.js').RecordSetFilter} RecordSetFilter
+ * @typedef {import('./RecordSet-RecordProvider-Base.js').RecordSetResult} RecordSetResult
+ *
+ * @typedef {{
+ *  getJSON(pOptionsOrURL: string | Record<string, any>, fCallback: RestClientCallback): void,
+ *  putJSON(pOptions: Record<string, any>, fCallback: RestClientCallback): void,
+ *  postJSON(pOptions: Record<string, any>, fCallback: RestClientCallback): void,
+ *  patchJSON(pOptions: Record<string, any>, fCallback: RestClientCallback): void,
+ *  headJSON(pOptions: Record<string, any>, fCallback: RestClientCallback): void,
+ *  delJSON(pOptions: Record<string, any>, fCallback: RestClientCallback): void,
+ *  getRawText(pOptionsOrURL: string | Record<string, any>, fCallback: RestClientCallback): void,
+ * }} RestClient
+ */
+
+/**
+ * Class representing a data change detection provider for Pict dynamic forms.
+ * @extends libRecordSetProviderBase
+ */
+class RecordSetProvider extends libRecordSetProviderBase
+{
+	/**
+	 * Creates an instance of RecordSetProvider.
+	 * @param {import('fable')} pFable - The Fable object.
+	 * @param {Record<string, any>} [pOptions] - Custom options for the provider.
+	 * @param {string} [pServiceHash] - The service hash.
+	 */
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+
+		/** @type {RestClient} */
+		this.restClient;
+		/** @type {Record<string, any>} */
+		this.options;
+		/** @type {import('fable')} */
+		this.fable;
+		/** @type {import('pict')} */
+		this.pict;
+		//TODO: make this typedef better
+		/** @type {Record<string, any>} */
+		this._Schema = { };
+	}
+
+	/**
+	 * @typedef {(error?: Error, result?: T) => void} RecordSetCallback
+	 * @template T = Record<string, any>
+	 */
+
+	/**
+	 * Get a record by its ID or GUID.
+	 *
+	 * @param {string|number} pIDOrGuid - The ID or GUID of the record.
+	 */
+	async getRecord(pIDOrGuid)
+	{
+		if (!this.options.Entity)
+		{
+			throw new Error('Entity is not defined in the provider options.');
+		}
+		if (typeof pIDOrGuid === 'string' && isNaN(parseInt(pIDOrGuid)))
+		{
+			return this.getRecordByGUID(pIDOrGuid);
+		}
+		if (this.pict.LogNoisiness > 1)
+		{
+			this.pict.log.info(`Reading ${this.options.Entity} record by ID`, { ID: pIDOrGuid });
+		}
+		return new Promise((resolve, reject) =>
+		{
+			this.restClient.getJSON(`${this.options.URLPrefix}${this.options.Entity}/${pIDOrGuid}`, (error, response, result) =>
+			{
+				if (error)
+				{
+					return reject(error);
+				}
+				resolve(result);
+			});
+		});
+	}
+
+	/**
+	 * Get a record by its ID or GUID.
+	 *
+	 * @param {string|number} pGuid - The ID or GUID of the record.
+	 */
+	async getRecordByGUID(pGuid)
+	{
+		if (!this.options.Entity)
+		{
+			throw new Error('Entity is not defined in the provider options.');
+		}
+		if (this.pict.LogNoisiness > 1)
+		{
+			this.pict.log.info(`Reading ${this.options.Entity} record by GUID`, { GUID: pGuid });
+		}
+		return new Promise((resolve, reject) =>
+		{
+			this.restClient.getJSON(`${this.options.URLPrefix}${this.options.Entity}s/FilteredTo/FBV~GUID${this.options.Entity}~EQ~${encodeURIComponent(pGuid)}`, (error, response, result) =>
+			{
+				if (error)
+				{
+					return reject(error);
+				}
+				resolve(result[0]);
+			});
+		});
+	}
+
+	/**
+	 * Read records from the provider.
+	 *
+	 * @param {RecordSetFilter} pOptions - Options for the read operation.
+	 * @return {Promise<RecordSetResult>} - The result of the read operation.
+	 */
+	async getRecords(pOptions)
+	{
+		if (!this.options.Entity && !pOptions.Entity)
+		{
+			throw new Error('Entity is not defined in the provider options.');
+		}
+		if (this.pict.LogNoisiness > 1)
+		{
+			this.pict.log.info(`Reading ${this.options.Entity} records`, { Options: pOptions });
+		}
+		const filterString = pOptions.FilterString ? `/FilteredTo/${pOptions.FilterString}` : '';
+		const pagination = `/${pOptions.Offset || 0}/${pOptions.PageSize || 250}`;
+		//TODO: lite support / other variants?
+		return new Promise((resolve, reject) =>
+		{
+			this.restClient.getJSON(`${this.options.URLPrefix}${this.options.Entity || pOptions.Entity}s${filterString}${pagination}`, (error, response, result) =>
+			{
+				if (error)
+				{
+					return reject(error);
+				}
+				resolve({ Records: result, Facets: { } });
+			});
+		});
+	}
+
+	/**
+	 * Read records from the provider.
+	 *
+	 * @param {string} [pFilterString] - The filter string to apply.
+	 * @param {number} [pOffset] - The starting record number for pagination.
+	 * @param {number} [pPageSize] - The number of records to return.
+	 * @return {Promise<RecordSetResult>} - The result of the read operation.
+	 */
+	async getRecordsInline(pFilterString = '', pOffset = 0, pPageSize = 250)
+	{
+		return this.getRecords({ FilterString: pFilterString, Offset: pOffset, PageSize: pPageSize });
+	}
+
+	/**
+	 * Read records from the provider.
+	 *
+	 * @param {RecordSetFilter} pOptions - Options for the read operation.
+	 */
+	async getRecordSetCount(pOptions)
+	{
+		if (!this.options.Entity && !pOptions.Entity)
+		{
+			throw new Error('Entity is not defined in the provider options.');
+		}
+		if (this.pict.LogNoisiness > 1)
+		{
+			this.pict.log.info(`Counting ${this.options.Entity} records`, { Options: pOptions });
+		}
+		const filterString = pOptions.FilterString ? `/FilteredTo/${pOptions.FilterString}` : '';
+		//TODO: lite support / other variants?
+		return new Promise((resolve, reject) =>
+		{
+			this.restClient.getJSON(`${this.options.URLPrefix}${this.options.Entity || pOptions.Entity}s/Count${filterString}`, (error, response, result) =>
+			{
+				if (error)
+				{
+					return reject(error);
+				}
+				resolve(result);
+			});
+		});
+	}
+
+	/**
+	 * Create a new record.
+	 *
+	 * @param {Record<string, any>} pRecord - The record to create.
+	 */
+	async createRecord(pRecord)
+	{
+		return new Promise((resolve, reject) =>
+		{
+		if (this.pict.LogNoisiness > 1)
+		{
+			this.pict.log.info(`Creating record ${this.options.Entity}`, { Record: pRecord });
+		}
+			this.restClient.postJSON({
+				url: `${this.options.URLPrefix}${this.options.Entity}`,
+				body: pRecord,
+			}, (error, response, result) =>
+			{
+				if (error)
+				{
+					return reject(error);
+				}
+				resolve(result);
+			});
+		});
+	}
+
+	/**
+	 * Update a record.
+	 *
+	 * @param {Record<string, any>} pRecord - The record to update.
+	 */
+	async updateRecord(pRecord)
+	{
+		if (this.pict.LogNoisiness > 1)
+		{
+			this.pict.log.info(`Updating record ${this.options.Entity} ${pRecord[`ID${this.options.Entity}`]}`);
+		}
+		return new Promise((resolve, reject) =>
+		{
+			this.restClient.putJSON({
+				url: `${this.options.URLPrefix}${this.options.Entity}`,
+				body: pRecord,
+			}, (error, response, result) =>
+			{
+				if (error)
+				{
+					return reject(error);
+				}
+				resolve(result);
+			});
+		});
+	}
+
+	/**
+	 * Delete a record.
+	 *
+	 * @param {Record<string, any>} pRecord - The record to delete.
+	 */
+	async deleteRecord(pRecord)
+	{
+		if (this.pict.LogNoisiness > 1)
+		{
+			this.pict.log.info(`Deleting record ${this.options.Entity} ${pRecord[`ID${this.options.Entity}`]}`);
+		}
+		return new Promise((resolve, reject) =>
+		{
+			this.restClient.delJSON({
+				url: `${this.options.URLPrefix}${this.options.Entity}/${pRecord[`ID${this.options.Entity}`]}`,
+				body: pRecord,
+			}, (error, response, result) =>
+			{
+				if (error)
+				{
+					return reject(error);
+				}
+				resolve(result);
+			});
+		});
+	}
+
+	/**
+	 * Read a record.
+	 *
+	 * @param {string|number} pIDOrGuid - The ID or GUID of the record.
+	 */
+	async readRecord(pIDOrGuid)
+	{
+		return this.getRecord(pIDOrGuid);
+	}
+
+	/**
+	 * Read records from the provider.
+	 *
+	 * @param {RecordSetFilter} pOptions - Options for the read operation.
+	 * @return {Promise<RecordSetResult>} - The result of the read operation.
+	 */
+	async readRecords(pOptions)
+	{
+		return this.getRecords(pOptions);
+	}
+
+	/**
+	 * Clone a record.
+	 *
+	 * @param {Record<string, any>} pRecord - The record to clone.
+	 */
+	async cloneRecord(pRecord)
+	{
+		return this.createRecord(this.cleanRecord(pRecord));
+	}
+
+	/**
+	 * Remove any intrinsic identifiers from a record.
+	 *
+	 * @param {Record<string, any>} pRecord - The record to clean.
+	 */
+	cleanRecord(pRecord)
+	{
+		delete pRecord[`ID${this.options.Entity}`];
+		delete pRecord[`GUID${this.options.Entity}`];
+		return pRecord;
+	}
+
+	/**
+	 * @param {(error?: Error) => void} fCallback - The callback function.
+	 */
+	onInitializeAsync(fCallback)
+	{
+		this.fable.log.info('Initializing RecordSetProvider-MeadowEndpoints');
+		this.restClient = this.fable.RestClient;
+		this.restClient.getJSON(`${this.options.URLPrefix}${this.options.Entity}/Schema`, (error, response, result) =>
+		{
+			if (error)
+			{
+				this._Schema = { };
+				return fCallback(error);
+			}
+			this._Schema = result;
+			return fCallback(null);
+		});
+	}
+
+	get recordSchema()
+	{
+		return this._Schema;
+	}
+}
+
+module.exports = RecordSetProvider;

package/source/providers/RecordSet-Router.js

@@ -0,0 +1,64 @@
+const libPictProvider = require('pict-provider');
+const libPictRouter = require('pict-router');
+
+const _DEFAULT_PROVIDER_CONFIGURATION =
+{
+	ProviderIdentifier: 'Pict-RecordSet-Router',
+
+	AutoInitialize: true,
+	AutoInitializeOrdinal: 0
+}
+
+class PictRecordSetRouter extends libPictProvider
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		let tmpOptions = Object.assign({}, _DEFAULT_PROVIDER_CONFIGURATION, pOptions);
+		super(pFable, tmpOptions, pServiceHash);
+
+		/** @type {Record<string, any>} */
+		this.options;
+		/** @type {import('pict') & { PictSectionRecordSet: InstanceType<import('../Pict-Section-RecordSet.js')> }} */
+		this.pict;
+
+		this.pictRouter = null;
+	}
+
+	onInitialize()
+	{
+		if (!('PictRouter' in this.pict.providers))
+		{
+			this.pictRouter = this.pict.addProvider('PictRouter', { RouterMode: 'memory' }, libPictRouter);
+		}
+		else
+		{
+			this.pictRouter = this.pict.providers.PictRouter;
+		}
+		return super.onInitialize();
+	}
+
+	addRoutes(pRouter)
+	{
+		// TODO: Create some kind of state tracking to see if these routes have already been added
+		//this.pictRouter.addRoute('/PSRS/:RecordSet/List/:Begin/:Cap', "{~LV:Record~}");
+		this.pict.views['RSP-RecordSet-List'].addRoutes(pRouter);
+		this.pict.views['RSP-RecordSet-Read'].addRoutes(pRouter);
+		this.pict.views['RSP-RecordSet-Edit'].addRoutes(pRouter);
+		this.pict.views['RSP-RecordSet-Dashboard'].addRoutes(pRouter);
+
+		this.pict.PictSectionRecordSet.addRoutes(pRouter);
+	}
+
+	/**
+	 * Navigate to a given route (set the browser URL string, add to history, trigger router)
+	 * 
+	 * @param {string} pRoute - The route to navigate to
+	 */
+	navigate(pRoute)
+	{
+		this.pictRouter.navigate(pRoute);
+	}
+}
+
+module.exports = PictRecordSetRouter;
+module.exports.default_configuration = _DEFAULT_PROVIDER_CONFIGURATION;