@shko.online/dataverse-odata 0.1.0

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@shko.online/dataverse-odata",
+  "version": "0.1.0",
+  "description": "This package will help parse OData strings (only the Microsoft Dataverse subset). It can be used as a validator, or you can build some javascript library which consumes the output of this library.",
+  "scripts": {
+    "build": "npm run lint && node ../scripts/build.js",
+    "lint": "eslint",
+    "tsc": "tsc --project tsconfig.build.json",
+    "test": "jest --coverage --maxWorkers=4"
+  },
+  "exports": {
+    ".": {
+      "require": "./lib/cjs/index.js",
+      "import": "./lib/esm/index.js",
+      "types": "./lib/ts3.9/index.d.ts"
+    }
+  },
+  "main": "lib/cjs/index.js",
+  "module": "lib/esm/index.mjs",
+  "types": "lib/ts3.9/index.d.ts",
+  "typesVersions": {
+    "<3.8": {
+      "lib/ts3.9/*": [
+        "lib/ts3.4/*"
+      ]
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shko.online/dataverse-odata.git"
+  },
+  "keywords": [
+    "odata",
+    "dataverse",
+    "made-in-albania"
+  ],
+  "author": "Shko Online <sales@shko.online> (https://shko.online);Betim Beja",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/shko.online/dataverse-odata/issues"
+  },
+  "homepage": "https://github.com/shko.online/dataverse-odata#readme",
+  "devDependencies": {
+    "@babel/cli": "^7.20.7",
+    "@babel/core": "^7.20.12",
+    "@babel/plugin-proposal-class-properties": "^7.18.6",
+    "@babel/plugin-proposal-decorators": "^7.20.13",
+    "@babel/plugin-proposal-export-default-from": "^7.18.10",
+    "@babel/plugin-proposal-object-rest-spread": "^7.20.7",
+    "@babel/plugin-proposal-private-methods": "^7.18.6",
+    "@babel/plugin-proposal-private-property-in-object": "^7.20.5",
+    "@babel/plugin-syntax-dynamic-import": "^7.8.3",
+    "@babel/plugin-transform-runtime": "^7.19.6",
+    "@babel/preset-env": "^7.20.2",
+    "@babel/preset-flow": "^7.18.6",
+    "@babel/preset-react": "^7.18.6",
+    "@babel/preset-typescript": "^7.18.6",
+    "@emotion/babel-plugin": "^11.10.5",
+    "@jest/globals": "^29.4.2",
+    "@storybook/babel-plugin-require-context-hook": "^1.0.1",
+    "@typescript-eslint/eslint-plugin": "^5.40.1",
+    "@typescript-eslint/parser": "^5.40.1",
+    "babel-plugin-dynamic-import-node": "^2.3.3",
+    "babel-plugin-macros": "^3.1.0",
+    "copyfiles": "^2.4.1",
+    "eslint": "^8.25.0",
+    "jest": "^29.2.1",
+    "jest-environment-jsdom": "^29.2.1",
+    "ts-jest": "^29.0.3",
+    "ts-node": "^10.9.1",
+    "typescript": "^4.8.4"
+  }
+}

package/src/OData.types.d.ts

@@ -0,0 +1,61 @@
+export interface ODataError {
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+
+export interface ODataExpand {
+    $expand?: {
+        [relationship: string]: ODataExpandQuery;
+    };
+}
+
+export type ODataExpandQuery = ODataSelect & ODataExpand;
+
+export interface ODataFilter {
+    $filter?: StandardOperator;
+}
+
+export interface ODataFetch {
+    fetchXml?: XMLDocument;
+}
+
+export interface ODataSelect {
+    /**
+     * Attributes to select.
+     * Empty array equals to all Attributes.
+     */
+    $select?: string[];
+}
+
+export interface ODataTop {
+    $top?: number;
+}
+
+export type StandardOperators = 'eq' | 'ne' | 'gt' | 'ge' | 'lt' | 'le';
+
+export interface StandardOperator {
+    operator: StandardOperators;
+    /**
+     * The left side of the 'X' operator must be a property of the entity.
+     */
+    left: string;
+    /**
+     * The right side of the 'X' operator must be a constant value.
+     */
+    right: string | number;
+}
+
+export interface UnaryOperator {
+    operator: 'not';
+    right: StandardOperator;
+}
+
+export interface BinaryOperator {
+    operator: 'and' | 'or';
+    left: StandardOperator;
+    right: StandardOperator;
+}
+
+export type ODataQuery = ODataError & ODataExpand & ODataFilter & ODataSelect & ODataTop & ODataFetch;

package/src/getExpandFromParser.ts

@@ -0,0 +1,105 @@
+import type { ODataError, ODataExpand, ODataExpandQuery, ODataQuery } from './OData.types';
+import { getSelectFromParser } from './getSelectFromParser';
+
+/**
+ * Parses the $expand query
+ * @returns Returns true when the parse has an error
+ */
+export const getExpandFromParser = (parser: URLSearchParams, result: ODataQuery): boolean => {
+    const $expand = parser.get('$expand');
+    if ($expand !== null) {
+        result.$expand = {};
+
+        if (extractExpand($expand, result)) {
+            return true;
+        }
+    }
+    return false;
+};
+
+const extractExpand = (value: string, $expand: ODataExpand & ODataError) => {
+    const match = value.match(/^\s*(\w(\w|\d|_)*)\s*(,|\()?\s*/);
+    if (
+        match === null ||
+        (match[0].length < value.length && match[3] === null) ||
+        (match[0].length === value.length && match[3] !== undefined)
+    ) {
+        $expand.error = {
+            code: '0x0',
+            message: 'invalid expand expression',
+        };
+        return true;
+    }
+    let matchSeparator = match[3];
+    let matchLength = match[0].length;
+    if (matchSeparator !== '(') {
+        if ($expand.$expand !== undefined) {
+            $expand.$expand[match[1]] = { $select: [] };
+        }
+    } else {
+        const { index, error } = getClosingBracket(value.substring(matchLength));
+        if (error) {
+            $expand.error = {
+                code: '0x0',
+                message: error,
+            };
+            return true;
+        }
+
+        if ($expand.$expand !== undefined) {
+            const innerExpand = {} as ODataExpandQuery & ODataError;
+            const parser = new URLSearchParams('?' + value.substring(matchLength, matchLength + index));
+            if (getSelectFromParser(parser, innerExpand)) {
+                $expand.error = innerExpand.error;
+                return true;
+            }
+            if (getExpandFromParser(parser, innerExpand)) {
+                $expand.error = innerExpand.error;
+                return true;
+            }
+            if (innerExpand.$expand === undefined && innerExpand.$select === undefined) {
+                $expand.error = { code: '0x0', message: 'Empty expand' };
+                return true;
+            }
+            $expand.$expand[match[1]] = innerExpand;
+        }
+
+        matchLength = matchLength + index;
+        const secondMatch = value.substring(matchLength + 1).match(/\s*(,?)\s*d/);
+        if (secondMatch !== null) {
+            matchLength = matchLength + secondMatch[0].length;
+            if (secondMatch[1] !== null) {
+                matchSeparator = ',';
+            }
+        }
+    }
+
+    if (matchSeparator === ',') {
+        if (extractExpand(value.substring(matchLength), $expand)) {
+            return true;
+        }
+    }
+
+    return false;
+};
+
+const getClosingBracket = (value: string): { index: number; error?: string } => {
+    let depth = 1;
+    let startAt = 0;
+    while (depth > 0) {
+        const match = value.substring(startAt).match(/\(|\)/);
+        if (match === null) {
+            return { error: 'no closing bracket found', index: -1 };
+        }
+        if (match[0] === ')') {
+            depth -= 1;
+            if (depth === 0) {
+                return { index: match.index || 0 };
+            }
+        } else {
+            depth += 1;
+        }
+        startAt = (match.index || 0) + 1;
+    }
+    return { error: 'no closing bracket found', index: -1 };
+};

package/src/getFetchXmlFromParser.ts

@@ -0,0 +1,48 @@
+import type { ODataQuery } from './OData.types';
+
+/**
+ * Parses the $fetchXml query
+ * @returns Returns true when the parse has an error
+ */
+export const getFetchXmlFromParser = (parser: URLSearchParams, result: ODataQuery): boolean => {
+    const fetchXml = parser.get('fetchXml');
+    if (fetchXml !== null) {
+        const serializer = new DOMParser();
+        const fetchXmlDocument = serializer.parseFromString(fetchXml, 'text/xml');
+        if (fetchXmlDocument.documentElement.tagName === 'parsererror') {
+            result.error = {
+                code: '0x80040201',
+                message: 'Invalid XML.',
+            };
+            return true;
+        }
+        const entity = fetchXmlDocument
+            .evaluate('fetch/entity', fetchXmlDocument, null, XPathResult.ANY_TYPE, null)
+            .iterateNext() as Element;
+        if (fetchXmlDocument.documentElement.children.length != 1 || !entity || !entity.getAttribute('name')) {
+            result.error = {
+                code: '0x80041102',
+                message: 'Entity Name was not specified in FetchXml String.',
+            };
+            return true;
+        }
+        const invalidAttribute = fetchXmlDocument
+            .evaluate(
+                'fetch/entity/*[not(self::filter or self::order or self::link-entity or self::attribute or self::all-attributes or self::no-attrs)]',
+                fetchXmlDocument,
+                null,
+                XPathResult.ANY_TYPE,
+                null,
+            )
+            .iterateNext() as Element;
+        if (invalidAttribute) {
+            result.error = {
+                code: '0x8004111c',
+                message: `Invalid Child Node, valid nodes are filter, order, link-entity, attribute, all-attributes, no-attrs. NodeName = ${invalidAttribute.tagName} NodeXml = ${invalidAttribute.outerHTML}`,
+            };
+            return true;
+        }
+        result.fetchXml = fetchXmlDocument;
+    }
+    return false;
+};

package/src/getSelectFromParser.ts

@@ -0,0 +1,13 @@
+import type { ODataQuery } from './OData.types';
+
+/**
+ * Parses the $select query
+ * @returns Returns true when the parse has an error
+ */
+export const getSelectFromParser = (parser: URLSearchParams, result: ODataQuery): boolean => {
+    const $select = parser.get('$select');
+    if ($select !== null) {
+        result.$select = $select.split(',');
+    }
+    return false;
+};

package/src/getTopFromParser.ts

@@ -0,0 +1,27 @@
+import type { ODataQuery } from './OData.types';
+
+/**
+ * Parses the $top query
+ * @returns Returns true when the parse has an error
+ */
+export const getTopFromParser = (parser: URLSearchParams, result: ODataQuery): boolean => {
+    const $topValue = parser.get('$top');
+    if ($topValue !== null) {
+        let $top;
+        if (!$topValue.match(/^\d+$/) || ($top = parseInt($topValue)) < 0) {
+            result.error = {
+                code: '0x0',
+                message: `Invalid value '${$topValue}' for $top query option found. The $top query option requires a non-negative integer value.`,
+            };
+            return true;
+        } else if ($top === 0) {
+            result.error = {
+                code: '0x0',
+                message: `Invalid value for $top query option.`,
+            };
+            return true;
+        }
+        result.$top = $top;
+    }
+    return false;
+};

package/src/index.ts

@@ -0,0 +1,16 @@
+export type {
+    BinaryOperator,
+    ODataError,
+    ODataExpand,
+    ODataExpandQuery,
+    ODataFetch,
+    ODataFilter,
+    ODataQuery,
+    ODataSelect,
+    ODataTop,
+    StandardOperator,
+    StandardOperators,
+} from './OData.types';
+export { parseOData } from './parseOData';
+import { parseOData } from './parseOData';
+export default parseOData;

package/src/parseOData.ts

@@ -0,0 +1,23 @@
+import type { ODataQuery } from './OData.types';
+import { getTopFromParser } from './getTopFromParser';
+import { getSelectFromParser } from './getSelectFromParser';
+import { getExpandFromParser } from './getExpandFromParser';
+import { getFetchXmlFromParser } from './getFetchXmlFromParser';
+
+export const parseOData = (query: string) => {
+    const parser = new URLSearchParams(query);
+    const result = {} as ODataQuery;
+    if (getExpandFromParser(parser, result)) {
+        return result;
+    }
+    if (getSelectFromParser(parser, result)) {
+        return result;
+    }
+    if (getTopFromParser(parser, result)) {
+        return result;
+    }
+    if (getFetchXmlFromParser(parser, result)) {
+        return result;
+    }
+    return result;
+};

package/tests/OData-Parser.$expand.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from '@jest/globals';
+import { parseOData } from '../src';
+
+describe('parseOData $expand', () => {
+    test('parse $expand Account_Leads', () => {
+        const result = parseOData('?$expand=Account_Leads');
+        expect(result.error).toBeUndefined();
+        expect(result.$expand).not.toBeNull();
+        expect(result.$expand).not.toBeUndefined();
+        expect(result.$expand?.Account_Leads.$select).toEqual([]);
+    });
+
+    test('parse $expand Account_Leads and business_unit_accounts', () => {
+        const result = parseOData('?$expand=Account_Leads,business_unit_accounts');
+        expect(result.error).toBeUndefined();
+        expect(result.$expand).not.toBeNull();
+        expect(result.$expand).not.toBeUndefined();
+        expect(result.$expand?.Account_Leads.$select).toEqual([]);
+        expect(result.$expand?.business_unit_accounts.$select).toEqual([]);
+    });
+
+    test('parse $expand throws on Account_Leads without details', () => {
+        const result = parseOData('?$expand=Account_Leads()');
+        expect(result.error).not.toBeUndefined();
+        expect(result.error?.message).toEqual('Empty expand');
+    });
+
+    test('parse $expand Account_Leads with $select', () => {
+        const result = parseOData('?$expand=Account_Leads($select=name)');
+        expect(result.error).toBeUndefined();
+        expect(result.$expand).not.toBeNull();
+        expect(result.$expand).not.toBeUndefined();
+        expect(result.$expand?.Account_Leads).not.toBeNull();
+        expect(result.$expand?.Account_Leads).not.toBeUndefined();
+        expect(result.$expand?.Account_Leads.$select).not.toBeNull();
+        expect(result.$expand?.Account_Leads.$select).not.toBeUndefined();
+        expect(result.$expand?.Account_Leads.$select).toContain('name');
+    });
+});

package/tests/OData-Parser.$top.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from '@jest/globals';
+import { parseOData } from '../src';
+
+describe('parseOData $top', () => {
+    test('parse $top 5', () => {
+        const result = parseOData('?$top=5');
+        console.log(result);
+        expect(result.$top).toEqual(5);
+    });
+
+    test('parse $top errors for 1,0', () => {
+        const result = parseOData('?$select=name,numberofemployees&$top=1,0');
+        expect(result.error).not.toBeNull();
+        console.log(result.error);
+        expect(result.error?.code).toEqual('0x0');
+        expect(result.error?.message).toEqual(
+            `Invalid value '1,0' for $top query option found. The $top query option requires a non-negative integer value.`,
+        );
+    });
+
+    test('parse $top errors for negative value', () => {
+        const result = parseOData('?$select=name,numberofemployees&$top=-2');
+        expect(result.error).not.toBeNull();
+        expect(result.error?.code).toEqual('0x0');
+        expect(result.error?.message).toEqual(
+            `Invalid value '-2' for $top query option found. The $top query option requires a non-negative integer value.`,
+        );
+    });
+
+    test('parse $top errors for 0', () => {
+        const result = parseOData('?$select=name,numberofemployees&$top=0');
+        expect(result.error).not.toBeNull();
+        expect(result.error?.code).toEqual('0x0');
+        expect(result.error?.message).toEqual(`Invalid value for $top query option.`);
+    });
+});

package/tests/OData-Parser.fetchXml.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from '@jest/globals';
+import { parseOData } from '../src';
+
+describe('parseOData fetchXml', () => {
+    test('parse fetchXml account', () => {
+        const result = parseOData(
+            '?fetchXml=%3Cfetch%20mapping%3D%27logical%27%3E%3Centity%20name%3D%27account%27%3E%3Cattribute%20name%3D%27accountid%27%2F%3E%3Cattribute%20name%3D%27name%27%2F%3E%3Cattribute%20name%3D%27accountnumber%27%2F%3E%3C%2Fentity%3E%3C%2Ffetch%3E',
+        );
+        console.log(result);
+        expect(result.fetchXml?.documentElement.outerHTML).toEqual(
+            `<fetch mapping="logical"><entity name="account"><attribute name="accountid"/><attribute name="name"/><attribute name="accountnumber"/></entity></fetch>`,
+        );
+    });
+
+    test('parse fetchXml fails if invalid XML', () => {
+        const result = parseOData('?fetchXml=invalid');
+        expect(result.error).not.toBeNull();
+        console.log(result.error);
+        expect(result.error?.code).toEqual('0x80040201');
+        expect(result.error?.message).toEqual('Invalid XML.');
+    });
+
+    test('parse fetchXml fails if EntityName not specified', () => {
+        const result = parseOData('?fetchXml=<fetch><entity name=""></entity></fetch>');
+        expect(result.error).not.toBeNull();
+        console.log(result.error);
+        expect(result.error?.code).toEqual('0x80041102');
+        expect(result.error?.message).toEqual('Entity Name was not specified in FetchXml String.');
+    });
+
+    test('parse fetchXml fails if EntityName not specified', () => {
+        const result = parseOData('?fetchXml=<fetch><entity></entity></fetch>');
+        expect(result.error).not.toBeNull();
+        console.log(result.error);
+        expect(result.error?.code).toEqual('0x80041102');
+        expect(result.error?.message).toEqual('Entity Name was not specified in FetchXml String.');
+    });
+
+    test('parse fetchXml fails if EntityName not specified', () => {
+        const result = parseOData('?fetchXml=<entity></entity>');
+        expect(result.error).not.toBeNull();
+        console.log(result.error);
+        expect(result.error?.code).toEqual('0x80041102');
+        expect(result.error?.message).toEqual('Entity Name was not specified in FetchXml String.');
+    });
+
+    test('parse fetchXml fails if EntityName not specified', () => {
+        const result = parseOData('?fetchXml=<fetch></fetch>');
+        expect(result.error).not.toBeNull();
+        console.log(result.error);
+        expect(result.error?.code).toEqual('0x80041102');
+        expect(result.error?.message).toEqual('Entity Name was not specified in FetchXml String.');
+    });
+
+    test('parse fetchXml fails if invalid attribute specified', () => {
+        const result = parseOData('?fetchXml=<fetch><entity%20name="systemuser"><n%20/></entity></fetch>');
+        expect(result.error).not.toBeUndefined();
+        console.log(result.error);
+        expect(result.error?.code).toEqual('0x8004111c');
+        expect(result.error?.message).toEqual('Invalid Child Node, valid nodes are filter, order, link-entity, attribute, all-attributes, no-attrs. NodeName = n NodeXml = <n/>');
+    });
+});

package/tests/OData-Parser.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, test } from '@jest/globals';
+import { parseOData } from '../src';
+
+describe('parse odata', () => {
+    test('parse $select', () => {
+        const result = parseOData('?$select=name,numberofemployees$top=5');
+        expect(result.$select).not.toBeNull();
+        expect(result.$select).toContain('name');
+    });
+
+    test('$select and $expand', () => {
+        const result = parseOData('?$select2=name,numberofemployees&$expand=Account_Leads($select=name)');
+        expect(result.$select).not.toBeNull();
+        expect(result.$expand).not.toBeNull();
+        expect(result.$expand?.Account_Leads).not.toBeNull();
+    });
+});

package/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+    "extends": "./tsconfig.json",
+    "exclude": [
+        "tests",
+        "lib",
+        "node_modules",
+        "jest.config.ts"
+    ]
+}

package/tsconfig.json

@@ -0,0 +1,36 @@
+{
+    "compilerOptions": {
+        "jsx": "react",
+        "allowSyntheticDefaultImports": true,
+        "esModuleInterop": true,
+        "target": "es5",
+        "lib": [
+            "es5",
+            "es6",
+            "dom"
+        ],
+        "module": "ES6",
+        "moduleResolution": "node",
+        "noEmit": false,
+        "outDir": "lib",
+        "resolveJsonModule": true,
+        "declaration": true,
+        "declarationMap": true,
+        "sourceMap": true,       
+        "baseUrl": ".",       
+        "typeRoots": [
+            "./node_modules/@types"
+        ]
+    },
+    "exclude": [
+        "node_modules",
+        "wwwroot",
+        "lib"
+    ],
+    "include": [
+        "src",
+        "tests",
+        "__type-tests__",
+        "__test-components__"
+    ]
+}