qast 1.0.0

package/dist/parser/validator.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateQuery = validateQuery;
+exports.extractFields = extractFields;
+exports.extractOperators = extractOperators;
+const errors_1 = require("../errors");
+const ast_1 = require("../types/ast");
+/**
+ * Validate an AST against whitelist options
+ */
+function validateQuery(ast, whitelist) {
+    validateNode(ast, whitelist);
+}
+/**
+ * Recursively validate a node
+ */
+function validateNode(node, whitelist) {
+    if ((0, ast_1.isComparisonNode)(node)) {
+        validateComparisonNode(node, whitelist);
+    }
+    else if ((0, ast_1.isLogicalNode)(node)) {
+        validateLogicalNode(node, whitelist);
+    }
+}
+/**
+ * Validate a comparison node
+ */
+function validateComparisonNode(node, whitelist) {
+    // Validate field
+    if (whitelist.allowedFields && whitelist.allowedFields.length > 0) {
+        if (!whitelist.allowedFields.includes(node.field)) {
+            throw new errors_1.ValidationError(`Field '${node.field}' is not allowed. Allowed fields: ${whitelist.allowedFields.join(', ')}`, node.field);
+        }
+    }
+    // Validate operator
+    if (whitelist.allowedOperators && whitelist.allowedOperators.length > 0) {
+        if (!whitelist.allowedOperators.includes(node.op)) {
+            throw new errors_1.ValidationError(`Operator '${node.op}' is not allowed. Allowed operators: ${whitelist.allowedOperators.join(', ')}`, node.field, node.op);
+        }
+    }
+    // Validate operator-value combination
+    if (node.op === 'in' && !Array.isArray(node.value)) {
+        throw new errors_1.ValidationError(`Operator 'in' requires an array value, got ${typeof node.value}`, node.field, node.op);
+    }
+}
+/**
+ * Validate a logical node
+ */
+function validateLogicalNode(node, whitelist) {
+    // Recursively validate left and right children
+    validateNode(node.left, whitelist);
+    validateNode(node.right, whitelist);
+}
+/**
+ * Extract all fields used in an AST
+ */
+function extractFields(ast) {
+    const fields = [];
+    extractFieldsRecursive(ast, fields);
+    return [...new Set(fields)]; // Return unique fields
+}
+/**
+ * Recursively extract fields from a node
+ */
+function extractFieldsRecursive(node, fields) {
+    if ((0, ast_1.isComparisonNode)(node)) {
+        fields.push(node.field);
+    }
+    else if ((0, ast_1.isLogicalNode)(node)) {
+        extractFieldsRecursive(node.left, fields);
+        extractFieldsRecursive(node.right, fields);
+    }
+}
+/**
+ * Extract all operators used in an AST
+ */
+function extractOperators(ast) {
+    const operators = [];
+    extractOperatorsRecursive(ast, operators);
+    return [...new Set(operators)]; // Return unique operators
+}
+/**
+ * Recursively extract operators from a node
+ */
+function extractOperatorsRecursive(node, operators) {
+    if ((0, ast_1.isComparisonNode)(node)) {
+        operators.push(node.op);
+    }
+    else if ((0, ast_1.isLogicalNode)(node)) {
+        extractOperatorsRecursive(node.left, operators);
+        extractOperatorsRecursive(node.right, operators);
+    }
+}
+//# sourceMappingURL=validator.js.map

package/dist/parser/validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../../src/parser/validator.ts"],"names":[],"mappings":"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"}

package/dist/types/ast.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Supported comparison operators
+ */
+export type Operator = 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'contains';
+/**
+ * Supported value types in comparisons
+ */
+export type QastValue = string | number | boolean | string[] | number[];
+/**
+ * Logical operator type
+ */
+export type LogicalOperator = 'AND' | 'OR';
+/**
+ * Comparison node representing a field comparison operation
+ */
+export interface ComparisonNode {
+    type: 'COMPARISON';
+    field: string;
+    op: Operator;
+    value: QastValue;
+}
+/**
+ * Logical node representing a logical operation (AND/OR) between two nodes
+ */
+export interface LogicalNode {
+    type: LogicalOperator;
+    left: QastNode;
+    right: QastNode;
+}
+/**
+ * Root AST node type - can be either a comparison or a logical operation
+ */
+export type QastNode = LogicalNode | ComparisonNode;
+/**
+ * Type guard to check if a node is a ComparisonNode
+ */
+export declare function isComparisonNode(node: QastNode): node is ComparisonNode;
+/**
+ * Type guard to check if a node is a LogicalNode
+ */
+export declare function isLogicalNode(node: QastNode): node is LogicalNode;
+/**
+ * Options for parsing queries
+ */
+export interface ParseOptions {
+    /**
+     * List of allowed field names. If provided, only these fields can be used in queries.
+     */
+    allowedFields?: string[];
+    /**
+     * List of allowed operators. If provided, only these operators can be used in queries.
+     */
+    allowedOperators?: Operator[];
+    /**
+     * Whether to validate the query against whitelists after parsing
+     */
+    validate?: boolean;
+}
+/**
+ * Options for query validation
+ */
+export interface WhitelistOptions {
+    /**
+     * List of allowed field names
+     */
+    allowedFields?: string[];
+    /**
+     * List of allowed operators
+     */
+    allowedOperators?: Operator[];
+}
+//# sourceMappingURL=ast.d.ts.map

package/dist/types/ast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../../src/types/ast.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,KAAK,GAAG,KAAK,GAAG,IAAI,GAAG,UAAU,CAAC;AAErF;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC;AAExE;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,IAAI,CAAC;AAE3C;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,QAAQ,CAAC;IACb,KAAK,EAAE,SAAS,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,eAAe,CAAC;IACtB,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,QAAQ,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,WAAW,GAAG,cAAc,CAAC;AAEpD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,IAAI,cAAc,CAEvE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,IAAI,WAAW,CAEjE;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IAEzB;;OAEG;IACH,gBAAgB,CAAC,EAAE,QAAQ,EAAE,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IAEzB;;OAEG;IACH,gBAAgB,CAAC,EAAE,QAAQ,EAAE,CAAC;CAC/B"}

package/dist/types/ast.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isComparisonNode = isComparisonNode;
+exports.isLogicalNode = isLogicalNode;
+/**
+ * Type guard to check if a node is a ComparisonNode
+ */
+function isComparisonNode(node) {
+    return node.type === 'COMPARISON';
+}
+/**
+ * Type guard to check if a node is a LogicalNode
+ */
+function isLogicalNode(node) {
+    return node.type === 'AND' || node.type === 'OR';
+}
+//# sourceMappingURL=ast.js.map

package/dist/types/ast.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast.js","sourceRoot":"","sources":["../../src/types/ast.ts"],"names":[],"mappings":";;AA0CA,4CAEC;AAKD,sCAEC;AAZD;;GAEG;AACH,SAAgB,gBAAgB,CAAC,IAAc;IAC7C,OAAO,IAAI,CAAC,IAAI,KAAK,YAAY,CAAC;AACpC,CAAC;AAED;;GAEG;AACH,SAAgB,aAAa,CAAC,IAAc;IAC1C,OAAO,IAAI,CAAC,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC;AACnD,CAAC"}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "qast",
+  "version": "1.0.0",
+  "description": "Query to AST to ORM - Parse human-readable query strings into AST and transform them into ORM-compatible filters",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "query",
+    "parser",
+    "ast",
+    "orm",
+    "prisma",
+    "typeorm",
+    "sequelize",
+    "filter",
+    "typescript",
+    "query-string",
+    "filtering",
+    "api"
+  ],
+  "author": "https://x.com/hocestnonsatis",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hocestnonsatis/qast.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hocestnonsatis/qast/issues"
+  },
+  "homepage": "https://github.com/hocestnonsatis/qast#readme",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.5.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "@prisma/client": "*",
+    "typeorm": "*",
+    "sequelize": "*"
+  },
+  "peerDependenciesMeta": {
+    "@prisma/client": {
+      "optional": true
+    },
+    "typeorm": {
+      "optional": true
+    },
+    "sequelize": {
+      "optional": true
+    }
+  }
+}
+