@gasboost/query 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gasboost
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/Filter.d.ts

@@ -0,0 +1,9 @@
+import { Operator } from "./FilterOperator";
+export { Operator as Operand };
+export declare class Filter {
+    private column;
+    private operand;
+    private criteria;
+    constructor(column: string, operand: Operator, values: (string | number | Date | boolean)[]);
+    isFullfiled(record: Record<string, any>): boolean;
+}

package/dist/Filter.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Filter = void 0;
+const FilterOperand_1 = require("./FilterOperand");
+const FilterOperator_1 = require("./FilterOperator");
+class Filter {
+    column;
+    operand;
+    criteria;
+    constructor(column, operand, values) {
+        this.column = column;
+        this.operand = new FilterOperator_1.FilterOperator(operand);
+        this.criteria = new FilterOperand_1.FilterOperand(values);
+        const isString = this.criteria.isString();
+        if (this.criteria.isStringOrBoolean() &&
+            this.operand.isMoreThanOrLessThan()) {
+            throw new Error(`Operand ${operand} is not supported for type`);
+        }
+        if (!isString && this.operand.isStringOperator()) {
+            throw new Error(`Operand ${operand} is not supported for type`);
+        }
+        if (this.criteria.isStringOrBoolean() &&
+            !isString &&
+            !this.operand.isEqualityOperator()) {
+            throw new Error(`Operand ${operand} is not supported for type`);
+        }
+    }
+    // レコードがフィルター条件を満たすかどうか
+    isFullfiled(record) {
+        const value = record[this.column];
+        // 日付を比較する
+        if (this.criteria.isDate()) {
+            const recordTime = value instanceof Date ? value.getTime() : NaN;
+            const criteriaTimes = this.criteria.getTimes();
+            return this.operand.compareNumber(recordTime, criteriaTimes);
+        }
+        // 文字列を比較する
+        if (this.criteria.isString()) {
+            const criteriaValues = this.criteria.getValue();
+            if (typeof value !== "string") {
+                return false;
+            }
+            return this.operand.compareString(value, criteriaValues);
+        }
+        // booleanを比較する
+        if (this.criteria.isStringOrBoolean()) {
+            const criteriaValues = this.criteria.getValue();
+            return this.operand.compare(value, criteriaValues);
+        }
+        // 数値を比較する
+        const criteria = this.criteria.getValue();
+        return this.operand.compareNumber(value, criteria);
+    }
+}
+exports.Filter = Filter;

package/dist/FilterOperand.d.ts

@@ -0,0 +1,9 @@
+export declare class FilterOperand {
+    private values;
+    constructor(values: (string | number | Date | boolean)[]);
+    isDate(): boolean;
+    getValue(): (string | number | boolean | Date)[];
+    getTimes(): number[];
+    isStringOrBoolean(): boolean;
+    isString(): boolean;
+}

package/dist/FilterOperand.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FilterOperand = void 0;
+class FilterOperand {
+    values;
+    constructor(values) {
+        this.values = values;
+        if (values.length === 0)
+            throw new Error("values must not be empty");
+        const firstType = typeof values[0];
+        if (firstType === "object")
+            return;
+        const isSameType = values.every((v) => v !== null && v !== undefined && typeof v === firstType);
+        if (!isSameType) {
+            throw new Error("values must be all the same type");
+        }
+    }
+    isDate() {
+        return Object.prototype.toString.call(this.values[0]) === "[object Date]";
+    }
+    getValue() {
+        return this.values;
+    }
+    getTimes() {
+        if (!this.isDate()) {
+            throw new Error("values are not Date type");
+        }
+        return this.values.map((v) => v.getTime());
+    }
+    isStringOrBoolean() {
+        return (typeof this.values[0] === "string" || typeof this.values[0] === "boolean");
+    }
+    isString() {
+        return typeof this.values[0] === "string";
+    }
+}
+exports.FilterOperand = FilterOperand;

package/dist/FilterOperator.d.ts

@@ -0,0 +1,11 @@
+export type Operator = "=" | "<" | ">" | "<=" | ">=" | "!=" | "*" | "!*" | "^*" | "*$";
+export declare class FilterOperator {
+    private operand;
+    constructor(operand: Operator);
+    isMoreThanOrLessThan(): boolean;
+    isStringOperator(): boolean;
+    isEqualityOperator(): boolean;
+    compareNumber(value: number, criteria: number[]): boolean;
+    compare(value: any, criteria: any[]): boolean;
+    compareString(value: string, criteria: string[]): boolean;
+}

package/dist/FilterOperator.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FilterOperator = void 0;
+class FilterOperator {
+    operand;
+    constructor(operand) {
+        this.operand = operand;
+    }
+    isMoreThanOrLessThan() {
+        return (this.operand === "<" ||
+            this.operand === ">" ||
+            this.operand === "<=" ||
+            this.operand === ">=");
+    }
+    isStringOperator() {
+        return (this.operand === "*" ||
+            this.operand === "!*" ||
+            this.operand === "^*" ||
+            this.operand === "*$");
+    }
+    isEqualityOperator() {
+        return this.operand === "=" || this.operand === "!=";
+    }
+    compareNumber(value, criteria) {
+        switch (this.operand) {
+            case "=":
+                return criteria.some((time) => time === value);
+            case "<":
+                return value < Math.min(...criteria);
+            case ">":
+                return value > Math.max(...criteria);
+            case "<=":
+                return value <= Math.min(...criteria);
+            case ">=":
+                return value >= Math.max(...criteria);
+            case "!=":
+                return !criteria.every((time) => time === value);
+            default:
+                throw new Error(`Operand ${this.operand} is not supported for number`);
+        }
+    }
+    compare(value, criteria) {
+        switch (this.operand) {
+            case "=":
+                return criteria.includes(value);
+            case "!=":
+                return !criteria.includes(value);
+            default:
+                throw new Error(`Operand ${this.operand} is not supported for type`);
+        }
+    }
+    compareString(value, criteria) {
+        switch (this.operand) {
+            case "=":
+                return criteria.includes(value);
+            case "!=":
+                return !criteria.includes(value);
+            case "*":
+                return criteria.some((needle) => value.includes(needle));
+            case "!*":
+                return criteria.every((needle) => !value.includes(needle));
+            case "^*":
+                return criteria.some((prefix) => value.startsWith(prefix));
+            case "*$":
+                return criteria.some((suffix) => value.endsWith(suffix));
+            default:
+                throw new Error(`Operand ${this.operand} is not supported for string`);
+        }
+    }
+}
+exports.FilterOperator = FilterOperator;

package/dist/Join.d.ts

@@ -0,0 +1,19 @@
+import type { Query } from "./Query";
+import type { TableDefinition } from "./TableDefinition";
+export declare class Join<T extends readonly TableDefinition[], N extends T[number]["name"] = T[number]["name"]> {
+    readonly table: N;
+    readonly localKey: string;
+    readonly foreignKey: string;
+    readonly query: Query<T, N> | null;
+    constructor({ table, localKey, foreignKey, query, }: {
+        table: N;
+        localKey: string;
+        foreignKey: string;
+        query?: Query<T, N> | null;
+    });
+    combine(parents: Record<string, unknown>[], children: Record<string, unknown>[]): Record<string, unknown>[];
+}
+export type JoinedRecord = {
+    readonly parent: Record<string, unknown>;
+    readonly children: Record<string, unknown>[];
+};

package/dist/Join.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Join = void 0;
+class Join {
+    table;
+    localKey;
+    foreignKey;
+    query;
+    constructor({ table, localKey, foreignKey, query = null, }) {
+        this.table = table;
+        this.localKey = localKey;
+        this.foreignKey = foreignKey;
+        this.query = query;
+    }
+    combine(parents, children) {
+        const childrenByKey = new Map();
+        for (const child of children) {
+            const key = child[this.foreignKey];
+            if (key === null || key === undefined) {
+                continue;
+            }
+            const matched = childrenByKey.get(key) ?? [];
+            matched.push(child);
+            childrenByKey.set(key, matched);
+        }
+        return parents.map((parent) => {
+            const key = parent[this.localKey];
+            const matchedChildren = key === null || key === undefined ? [] : (childrenByKey.get(key) ?? []);
+            return {
+                ...parent,
+                [this.table]: matchedChildren,
+            };
+        });
+    }
+}
+exports.Join = Join;

package/dist/OrderBy.d.ts

@@ -0,0 +1,6 @@
+export declare class OrderBy {
+    private column;
+    private direction;
+    constructor(column: string, direction: "asc" | "desc");
+    sort(a: Record<string, any>, b: Record<string, any>): number;
+}

package/dist/OrderBy.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OrderBy = void 0;
+class OrderBy {
+    column;
+    direction;
+    constructor(column, direction) {
+        this.column = column;
+        this.direction = direction;
+    }
+    sort(a, b) {
+        const av = a[this.column];
+        const bv = b[this.column];
+        if (av === bv)
+            return 0;
+        const result = av > bv ? 1 : -1;
+        if (this.direction === "asc")
+            return result;
+        if (this.direction === "desc")
+            return -result;
+        throw new Error(`Invalid sort direction: ${this.direction}`);
+    }
+}
+exports.OrderBy = OrderBy;

package/dist/Query.d.ts

@@ -0,0 +1,39 @@
+import type { z } from "zod";
+import { Filter, Operand } from "./Filter";
+import { Join } from "./Join";
+import { OrderBy } from "./OrderBy";
+import type { TableByName, TableDefinition } from "./TableDefinition";
+export type CriteriaValue<S extends z.ZodObject<any>, K extends keyof z.infer<S>> = z.infer<S>[K];
+export type Loader<T extends readonly TableDefinition[]> = <N extends T[number]["name"]>(table: N) => Promise<Record<string, unknown>[]>;
+export declare class Query<T extends readonly TableDefinition[], N extends T[number]["name"] = T[number]["name"]> {
+    private readonly requires;
+    private readonly options;
+    private orderByValue;
+    private limitValue;
+    private offsetValue;
+    private readonly joins;
+    private readonly tableName;
+    constructor({ tableName, requires, options, orderBy, limit, offset, joins, }: {
+        tableName: N;
+        requires?: Filter[];
+        options?: Filter[];
+        orderBy?: OrderBy | null;
+        limit?: number | null;
+        offset?: number | null;
+        joins?: Join<T>[];
+    });
+    getTableName(): N;
+    and<K extends keyof z.infer<TableByName<T, N>["schema"]>>(column: K, operand: Operand, values: CriteriaValue<TableByName<T, N>["schema"], K>[]): this;
+    or<K extends keyof z.infer<TableByName<T, N>["schema"]>>(column: K, operand: Operand, values: CriteriaValue<TableByName<T, N>["schema"], K>[]): this;
+    orderBy<K extends keyof z.infer<TableByName<T, N>["schema"]>>(column: K, order?: "asc" | "desc"): this;
+    limit(value: number): this;
+    offset(value: number): this;
+    join<RefName extends T[number]["name"], LocalKey extends keyof z.infer<TableByName<T, N>["schema"]>, RefKey extends keyof z.infer<TableByName<T, RefName>["schema"]>>(localKey: LocalKey, referenceTableName: RefName, referenceKey: RefKey, query?: Query<T, RefName>): this;
+    filter(records: Record<string, unknown>[]): Record<string, unknown>[];
+    sort(records: Record<string, unknown>[]): Record<string, unknown>[];
+    shift(records: Record<string, unknown>[]): Record<string, unknown>[];
+    cut(records: Record<string, unknown>[]): Record<string, unknown>[];
+    getJoins(): readonly Join<T>[];
+    apply(records: Record<string, unknown>[]): Record<string, unknown>[];
+    resolve(load: Loader<T>): Promise<Record<string, unknown>[]>;
+}

package/dist/Query.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Query = void 0;
+const Filter_1 = require("./Filter");
+const Join_1 = require("./Join");
+const OrderBy_1 = require("./OrderBy");
+class Query {
+    requires;
+    options;
+    orderByValue;
+    limitValue;
+    offsetValue;
+    joins;
+    tableName;
+    constructor({ tableName, requires = [], options = [], orderBy = null, limit = null, offset = null, joins = [], }) {
+        this.tableName = tableName;
+        this.requires = requires;
+        this.options = options;
+        this.orderByValue = orderBy;
+        this.limitValue = limit;
+        this.offsetValue = offset;
+        this.joins = joins;
+    }
+    getTableName() {
+        return this.tableName;
+    }
+    and(column, operand, values) {
+        this.requires.push(new Filter_1.Filter(column, operand, values));
+        return this;
+    }
+    or(column, operand, values) {
+        this.options.push(new Filter_1.Filter(column, operand, values));
+        return this;
+    }
+    orderBy(column, order = "asc") {
+        this.orderByValue = new OrderBy_1.OrderBy(column, order);
+        return this;
+    }
+    limit(value) {
+        this.limitValue = value;
+        return this;
+    }
+    offset(value) {
+        this.offsetValue = value;
+        return this;
+    }
+    join(localKey, referenceTableName, referenceKey, query) {
+        this.joins.push(new Join_1.Join({
+            table: referenceTableName,
+            localKey: localKey,
+            foreignKey: referenceKey,
+            query: query ?? null,
+        }));
+        return this;
+    }
+    filter(records) {
+        return records.filter((record) => {
+            const requires = this.requires.every((filter) => filter.isFullfiled(record));
+            const options = this.options.length === 0 ||
+                this.options.some((filter) => filter.isFullfiled(record));
+            return requires && options;
+        });
+    }
+    sort(records) {
+        if (this.orderByValue !== null) {
+            records.sort((a, b) => this.orderByValue.sort(a, b));
+        }
+        return records;
+    }
+    shift(records) {
+        if (this.offsetValue !== null && this.offsetValue > 0) {
+            records.splice(0, this.offsetValue);
+        }
+        return records;
+    }
+    cut(records) {
+        if (this.limitValue !== null && this.limitValue > 0) {
+            records.splice(this.limitValue);
+        }
+        return records;
+    }
+    getJoins() {
+        return this.joins;
+    }
+    apply(records) {
+        const filtered = this.filter(records);
+        const sorted = this.sort(filtered);
+        const shifted = this.shift(sorted);
+        return this.cut(shifted);
+    }
+    async resolve(load) {
+        let records = this.apply(await load(this.tableName));
+        for (const join of this.joins) {
+            const children = join.query !== null
+                ? await join.query.resolve(load)
+                : await load(join.table);
+            records = join.combine(records, children);
+        }
+        return records;
+    }
+}
+exports.Query = Query;

package/dist/TableDefinition.d.ts

@@ -0,0 +1,9 @@
+import type { z } from "zod";
+export type TableDefinition<N extends string = string, S extends z.ZodObject<any> = z.ZodObject<any>> = {
+    readonly name: N;
+    readonly schema: S;
+};
+export type TableByName<T extends readonly TableDefinition[], N extends T[number]["name"]> = Extract<T[number], {
+    name: N;
+}>;
+export type TableRecord<T extends readonly TableDefinition[], N extends T[number]["name"]> = z.infer<TableByName<T, N>["schema"]>;

package/dist/TableDefinition.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.js

@@ -0,0 +1 @@
+"use strict";

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@gasboost/query",
+  "version": "0.1.0",
+  "description": "Type-safe, storage-agnostic query engine powered by Zod",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gasboost/db.git",
+    "directory": "packages/query"
+  },
+  "license": "MIT",
+  "author": "tiger-oshima",
+  "keywords": [
+    "query",
+    "query-builder",
+    "database",
+    "zod",
+    "typescript",
+    "type-safe",
+    "join"
+  ],
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "zod": "^4.5.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "pack:check": "pnpm pack"
+  }
+}