@scarif/scarif-js 1.0.0

package/dist/utils/query-builder.js

@@ -0,0 +1,336 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryBuilderImpl = void 0;
+exports.buildQueryString = buildQueryString;
+const select_parser_1 = require("./select-parser");
+/**
+ * Chainable query builder implementation
+ */
+class QueryBuilderImpl {
+    constructor(table, executeFn) {
+        this.table = table;
+        this.executeFn = executeFn;
+        this.state = {
+            filters: {}
+        };
+    }
+    // ===========================================
+    // VALIDATION HELPERS
+    // ===========================================
+    /**
+     * Validates that a number is non-negative
+     */
+    validateNonNegative(value, paramName) {
+        if (value < 0) {
+            throw new Error(`${paramName} must be non-negative, got ${value}`);
+        }
+    }
+    /**
+     * Validates that a value is not null or undefined
+     */
+    validateNotNull(value, paramName) {
+        if (value === null || value === undefined) {
+            throw new Error(`${paramName} cannot be null or undefined`);
+        }
+    }
+    /**
+     * Validates that an array is not empty
+     */
+    validateNonEmptyArray(arr, paramName) {
+        if (!Array.isArray(arr)) {
+            throw new Error(`${paramName} must be an array`);
+        }
+        if (arr.length === 0) {
+            throw new Error(`${paramName} cannot be an empty array`);
+        }
+    }
+    /**
+     * Validates column name is a non-empty string
+     */
+    validateColumnName(column, paramName = 'column') {
+        if (typeof column !== 'string' || column.trim().length === 0) {
+            throw new Error(`${paramName} must be a non-empty string`);
+        }
+    }
+    // ===========================================
+    // SELECTION
+    // ===========================================
+    select(query) {
+        const parsed = (0, select_parser_1.parseSupabaseSelect)(query);
+        // Map parsed result to QueryState format
+        // Convert tableName to table for ParsedRelation
+        this.state.select = {
+            primaryColumns: parsed.primaryColumns,
+            associatedTables: parsed.associatedTables.map(t => ({
+                table: t.tableName,
+                columns: t.columns
+            }))
+        };
+        return this;
+    }
+    // ===========================================
+    // FILTERS
+    // ===========================================
+    /**
+     * Helper method to add object-based filters (eq, neq, gt, etc.)
+     */
+    addObjectFilter(key, column, value) {
+        this.validateColumnName(column);
+        this.validateNotNull(value, `Filter value for ${column}`);
+        if (!this.state.filters[key]) {
+            this.state.filters[key] = {};
+        }
+        this.state.filters[key][column] = value;
+        return this;
+    }
+    /**
+     * Helper method to add array-based filters (in, notIn)
+     */
+    addArrayFilter(key, column, values) {
+        this.validateColumnName(column);
+        this.validateNonEmptyArray(values, `Filter values for ${column}`);
+        if (!this.state.filters[key]) {
+            this.state.filters[key] = {};
+        }
+        this.state.filters[key][column] = values.map(String);
+        return this;
+    }
+    /**
+     * Helper method to add column list filters (isNull, isNotNull)
+     */
+    addColumnListFilter(key, column) {
+        this.validateColumnName(column);
+        if (!this.state.filters[key]) {
+            this.state.filters[key] = [];
+        }
+        this.state.filters[key].push(column);
+        return this;
+    }
+    eq(column, value) {
+        return this.addObjectFilter('eq', column, value);
+    }
+    neq(column, value) {
+        return this.addObjectFilter('neq', column, value);
+    }
+    gt(column, value) {
+        return this.addObjectFilter('gt', column, value);
+    }
+    gte(column, value) {
+        return this.addObjectFilter('gte', column, value);
+    }
+    lt(column, value) {
+        return this.addObjectFilter('lt', column, value);
+    }
+    lte(column, value) {
+        return this.addObjectFilter('lte', column, value);
+    }
+    like(column, value) {
+        return this.addObjectFilter('like', column, value);
+    }
+    ilike(column, value) {
+        return this.addObjectFilter('ilike', column, value);
+    }
+    in(column, values) {
+        return this.addArrayFilter('in', column, values);
+    }
+    notIn(column, values) {
+        return this.addArrayFilter('notIn', column, values);
+    }
+    isNull(column) {
+        return this.addColumnListFilter('isNull', column);
+    }
+    isNotNull(column) {
+        return this.addColumnListFilter('isNotNull', column);
+    }
+    // ===========================================
+    // ORDERING
+    // ===========================================
+    order(column, direction = 'asc') {
+        this.validateColumnName(column, 'order column');
+        if (!this.state.order)
+            this.state.order = [];
+        this.state.order.push({ column, direction });
+        return this;
+    }
+    // ===========================================
+    // PAGINATION
+    // ===========================================
+    limit(count) {
+        this.validateNonNegative(count, 'limit');
+        this.state.limit = count;
+        return this;
+    }
+    offset(count) {
+        this.validateNonNegative(count, 'offset');
+        this.state.offset = count;
+        return this;
+    }
+    range(from, to) {
+        this.validateNonNegative(from, 'range start');
+        this.validateNonNegative(to, 'range end');
+        if (to < from) {
+            throw new Error(`range end (${to}) must be >= range start (${from})`);
+        }
+        this.state.offset = from;
+        // Calculate limit: to is exclusive (like array.slice), so limit = to - from
+        this.state.limit = to - from;
+        return this;
+    }
+    // ===========================================
+    // RESPONSE MODIFIERS
+    // ===========================================
+    single() {
+        this.state.single = true;
+        // Only set limit if not already set to avoid overwriting user's limit()
+        if (this.state.limit === undefined) {
+            this.state.limit = 1;
+        }
+        return this;
+    }
+    // ===========================================
+    // THENABLE INTERFACE
+    // ===========================================
+    then(onfulfilled, onrejected) {
+        // Enforce required select()
+        if (!this.state.select) {
+            const error = new Error("select() is required. Use .select('*') to select all columns.");
+            return Promise.reject(error);
+        }
+        // Create the base promise from executeFn
+        const basePromise = this.executeFn(this.table, this.state);
+        // Transform the response based on single flag
+        const transformedPromise = basePromise.then(response => {
+            if (this.state.single) {
+                // Handle single result
+                if (response.error) {
+                    return response;
+                }
+                const data = Array.isArray(response.data) && response.data.length > 0
+                    ? response.data[0]
+                    : null;
+                return {
+                    ...response,
+                    data
+                };
+            }
+            return response;
+        });
+        // Always chain the handlers (Promise.then works with undefined handlers)
+        return transformedPromise.then(onfulfilled, onrejected);
+    }
+    catch(onrejected) {
+        return this.then().catch(onrejected);
+    }
+}
+exports.QueryBuilderImpl = QueryBuilderImpl;
+// ===========================================
+// QUERY STRING BUILDER
+// ===========================================
+/**
+ * Helper function to add object-based filter parameters to URLSearchParams
+ */
+function addObjectFilterParams(params, filter, filterType) {
+    if (filter) {
+        for (const [key, value] of Object.entries(filter)) {
+            params.append(`${key}[${filterType}]`, String(value));
+        }
+    }
+}
+/**
+ * Helper function to add array-based filter parameters to URLSearchParams
+ */
+function addArrayFilterParams(params, filter, filterType) {
+    if (filter) {
+        for (const [key, values] of Object.entries(filter)) {
+            params.append(`${key}[${filterType}]`, values.join(','));
+        }
+    }
+}
+/**
+ * Helper function to add column list filter parameters to URLSearchParams
+ */
+function addColumnListFilterParams(params, columns, filterType) {
+    if (columns) {
+        for (const column of columns) {
+            params.append(`${column}[${filterType}]`, 'true');
+        }
+    }
+}
+/**
+ * Builds URL query string from QueryState
+ *
+ * Transforms the internal QueryState structure into URL query parameters
+ * following the API's expected format:
+ * - Select columns: `select=col1,col2`
+ * - Relations: `with=table(col1,col2)`
+ * - Filters: `column[filterType]=value`
+ * - Ordering: `order=column.direction`
+ * - Pagination: `limit=N&offset=N`
+ *
+ * @param state - The query state containing all filters, selections, and modifiers
+ * @returns Query string with leading '?' if params exist, empty string otherwise
+ *
+ * @example
+ * ```typescript
+ * const state: QueryState = {
+ *   select: { primaryColumns: ['id', 'name'], associatedTables: [] },
+ *   filters: { eq: { status: 'active' } },
+ *   limit: 10
+ * };
+ * buildQueryString(state); // "?select=id,name&status[eq]=active&limit=10"
+ * ```
+ */
+function buildQueryString(state) {
+    const params = new URLSearchParams();
+    // Select columns and relations (transformed from parsed select)
+    if (state.select) {
+        // Primary columns
+        if (state.select.primaryColumns.length > 0) {
+            params.append('select', state.select.primaryColumns.join(','));
+        }
+        // Associated tables as 'with' parameters
+        if (state.select.associatedTables.length > 0) {
+            for (const relation of state.select.associatedTables) {
+                if (relation.columns && relation.columns.length > 0) {
+                    params.append('with', `${relation.table}(${relation.columns.join(',')})`);
+                }
+                else {
+                    params.append('with', relation.table);
+                }
+            }
+        }
+    }
+    // Filters - object-based filters
+    const { filters } = state;
+    addObjectFilterParams(params, filters.eq, 'eq');
+    addObjectFilterParams(params, filters.neq, 'neq');
+    addObjectFilterParams(params, filters.gt, 'gt');
+    addObjectFilterParams(params, filters.gte, 'gte');
+    addObjectFilterParams(params, filters.lt, 'lt');
+    addObjectFilterParams(params, filters.lte, 'lte');
+    addObjectFilterParams(params, filters.like, 'like');
+    addObjectFilterParams(params, filters.ilike, 'ilike');
+    // Filters - array-based filters
+    addArrayFilterParams(params, filters.in, 'in');
+    addArrayFilterParams(params, filters.notIn, 'notIn');
+    // Filters - column list filters
+    addColumnListFilterParams(params, filters.isNull, 'isNull');
+    addColumnListFilterParams(params, filters.isNotNull, 'isNotNull');
+    // Order
+    if (state.order && state.order.length > 0) {
+        const orderStr = state.order
+            .map(o => `${o.column}.${o.direction}`)
+            .join(',');
+        params.append('order', orderStr);
+    }
+    // Limit
+    if (state.limit !== undefined) {
+        params.append('limit', String(state.limit));
+    }
+    // Offset
+    if (state.offset !== undefined) {
+        params.append('offset', String(state.offset));
+    }
+    const queryString = params.toString();
+    return queryString ? `?${queryString}` : '';
+}

package/dist/utils/select-parser.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Result of parsing a Supabase-style select query string
+ */
+export interface ParsedQuery {
+    primaryColumns: string[];
+    associatedTables: {
+        tableName: string;
+        columns: string[];
+    }[];
+}
+/**
+ * Parses a Supabase/PostgREST-style select query string into structured data
+ *
+ * @param selectQuery - Select query string (e.g., "id, name, posts(title, content)")
+ * @returns Parsed query with primary columns and associated tables
+ *
+ * @example
+ * ```typescript
+ * parseSupabaseSelect('id, name, posts(title, content)')
+ * // Returns:
+ * // {
+ * //   primaryColumns: ['id', 'name'],
+ * //   associatedTables: [{ tableName: 'posts', columns: ['title', 'content'] }]
+ * // }
+ * ```
+ */
+export declare function parseSupabaseSelect(selectQuery: string): ParsedQuery;
+//# sourceMappingURL=select-parser.d.ts.map

package/dist/utils/select-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"select-parser.d.ts","sourceRoot":"","sources":["../../src/utils/select-parser.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,WAAW;IACxB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,gBAAgB,EAAE;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,EAAE,CAAC;KACnB,EAAE,CAAC;CACL;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,CAqEpE"}

package/dist/utils/select-parser.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSupabaseSelect = parseSupabaseSelect;
+/**
+ * Parses a Supabase/PostgREST-style select query string into structured data
+ *
+ * @param selectQuery - Select query string (e.g., "id, name, posts(title, content)")
+ * @returns Parsed query with primary columns and associated tables
+ *
+ * @example
+ * ```typescript
+ * parseSupabaseSelect('id, name, posts(title, content)')
+ * // Returns:
+ * // {
+ * //   primaryColumns: ['id', 'name'],
+ * //   associatedTables: [{ tableName: 'posts', columns: ['title', 'content'] }]
+ * // }
+ * ```
+ */
+function parseSupabaseSelect(selectQuery) {
+    // Remove extra whitespace and newlines
+    const normalized = selectQuery.replace(/\s+/g, ' ').trim();
+    const result = {
+        primaryColumns: [],
+        associatedTables: []
+    };
+    let i = 0;
+    let currentToken = '';
+    let parenDepth = 0;
+    while (i < normalized.length) {
+        const char = normalized[i];
+        if (char === '(') {
+            parenDepth++;
+            if (parenDepth === 1 && currentToken.trim()) {
+                // Start of associated table
+                const tableName = currentToken.trim();
+                i++; // Skip opening paren
+                // Extract content within parentheses
+                let tableContent = '';
+                let depth = 1;
+                while (i < normalized.length && depth > 0) {
+                    if (normalized[i] === '(')
+                        depth++;
+                    if (normalized[i] === ')')
+                        depth--;
+                    if (depth > 0)
+                        tableContent += normalized[i];
+                    i++;
+                }
+                // Parse columns for this table
+                const columns = tableContent
+                    .split(',')
+                    .map(col => col.trim())
+                    .filter(col => col.length > 0);
+                result.associatedTables.push({
+                    tableName,
+                    columns
+                });
+                currentToken = '';
+                parenDepth = 0;
+                continue;
+            }
+        }
+        else if (char === ',') {
+            if (parenDepth === 0 && currentToken.trim()) {
+                // Primary column
+                result.primaryColumns.push(currentToken.trim());
+                currentToken = '';
+            }
+            else if (parenDepth > 0) {
+                currentToken += char;
+            }
+        }
+        else {
+            currentToken += char;
+        }
+        i++;
+    }
+    // Add last token if it exists and we're not in parentheses
+    if (currentToken.trim() && parenDepth === 0) {
+        result.primaryColumns.push(currentToken.trim());
+    }
+    return result;
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@scarif/scarif-js",
+  "version": "1.0.0",
+  "description": "A TypeScript SDK for Scarif API services",
+  "keywords": [
+    "\"api",
+    "sdk",
+    "data\""
+  ],
+  "homepage": "https://github.com/GeneralTyres/stoorplek-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/GeneralTyres/stoorplek-sdk/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GeneralTyres/stoorplek-sdk.git"
+  },
+  "license": "MIT",
+  "author": "GeneralTyres",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "directories": {
+    "doc": "docs"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "test": "echo \"No tests yet\"",
+    "dev": "tsc --watch",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "undici-types": "^7.16.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.7",
+    "typescript": "^5.9.3"
+  }
+}