@onchaindb/sdk 2.3.0 → 4.0.0

package/src/model.ts

@@ -0,0 +1,359 @@
+import { OnDBClient } from './client';
+import { FieldConditionBuilder, LogicalOperator, QueryBuilder } from './query-sdk';
+import { AggregateSpec, SelectionMap } from './query-sdk';
+import { StoreResponse } from './types';
+
+// ── Where input types ─────────────────────────────────────────────────────────
+
+export type FieldFilter = {
+    // ── Equality ─────────────────────────────────────────────────────────────
+    equals?: any;
+    not?: any;
+    in?: any[];
+    notIn?: any[];
+    /** Case-sensitive membership check (unlike `in` which is case-insensitive). */
+    inDataset?: string[];
+
+    // ── Numeric / comparison ─────────────────────────────────────────────────
+    lt?: any;
+    lte?: any;
+    gt?: any;
+    gte?: any;
+    /** Exclusive range: from < value < to. */
+    between?: { from: any; to: any };
+
+    // ── String ───────────────────────────────────────────────────────────────
+    contains?: string;
+    startsWith?: string;
+    endsWith?: string;
+    containsCaseInsensitive?: string;
+    startsWithCaseInsensitive?: string;
+    endsWithCaseInsensitive?: string;
+    regex?: string;
+
+    // ── Presence ─────────────────────────────────────────────────────────────
+    isNotNull?: true;
+    exists?: boolean;
+
+    // ── IP ───────────────────────────────────────────────────────────────────
+    isLocalIp?: true;
+    isExternalIp?: true;
+    inCountry?: string;
+    /** CIDR range check. Always uses "$cidr" alias to avoid Scepter stack overflow. */
+    cidr?: string | string[];
+
+    // ── Misc ─────────────────────────────────────────────────────────────────
+    /** Array of keywords — matches if the field contains ANY of them (case-insensitive substring). */
+    keywords?: string[];
+    b64?: string;
+};
+
+/** Prisma-style where clause. Multiple top-level fields are implicitly ANDed. */
+export type WhereInput<T = any> = {
+    [K in keyof T]?: T[K] | FieldFilter;
+} & {
+    AND?: WhereInput<T>[];
+    OR?: WhereInput<T>[];
+    NOT?: WhereInput<T>[];
+};
+
+export type OrderByInput<T = any> = {
+    [K in keyof T]?: 'asc' | 'desc';
+};
+
+export type SelectInput<T = any> = {
+    [K in keyof T]?: boolean;
+};
+
+// ── Arg interfaces ────────────────────────────────────────────────────────────
+
+export interface FindManyArgs<T = any> {
+    where?: WhereInput<T>;
+    select?: SelectInput<T>;
+    orderBy?: OrderByInput<T>;
+    take?: number;
+    skip?: number;
+    /**
+     * Exclude soft-deleted records.
+     * - `true`  → filters out records where `deletedAt` exists
+     * - `string` → filters out records where the given field exists (custom delete key)
+     */
+    excludeDeleted?: boolean | string;
+}
+
+export type FindFirstArgs<T = any> = Omit<FindManyArgs<T>, 'take'>;
+
+export interface FindUniqueArgs<T = any> {
+    where: WhereInput<T>;
+    select?: SelectInput<T>;
+}
+
+export interface CreateArgs<T = any> {
+    data: Partial<T> & Record<string, any>;
+}
+
+export interface CreateManyArgs<T = any> {
+    data: Array<Partial<T> & Record<string, any>>;
+}
+
+export interface CountArgs<T = any> {
+    where?: WhereInput<T>;
+}
+
+export interface AggregateArgs<T = any> {
+    where?: WhereInput<T>;
+    /** Count all records */
+    _count?: boolean;
+    /** Sum numeric fields: { _sum: { age: true } } */
+    _sum?: { [K in keyof T]?: boolean };
+    /** Average numeric fields */
+    _avg?: { [K in keyof T]?: boolean };
+    /** Minimum value per field */
+    _min?: { [K in keyof T]?: boolean };
+    /** Maximum value per field */
+    _max?: { [K in keyof T]?: boolean };
+}
+
+// ── Where → LogicalOperator converter ────────────────────────────────────────
+
+const OPERATOR_KEYS = new Set([
+    'equals', 'not', 'in', 'notIn', 'inDataset',
+    'lt', 'lte', 'gt', 'gte', 'between',
+    'contains', 'startsWith', 'endsWith',
+    'containsCaseInsensitive', 'startsWithCaseInsensitive', 'endsWithCaseInsensitive',
+    'regex',
+    'isNotNull', 'exists',
+    'isLocalIp', 'isExternalIp', 'inCountry', 'cidr',
+    'keywords', 'b64',
+]);
+
+function buildConditions(where: WhereInput): LogicalOperator[] {
+    const conditions: LogicalOperator[] = [];
+
+    for (const [key, value] of Object.entries(where)) {
+        if (key === 'AND' && Array.isArray(value)) {
+            const inner = (value as WhereInput[]).flatMap(buildConditions);
+            if (inner.length > 0) conditions.push(LogicalOperator.And(inner));
+
+        } else if (key === 'OR' && Array.isArray(value)) {
+            const inner = (value as WhereInput[]).flatMap(buildConditions);
+            if (inner.length > 0) conditions.push(LogicalOperator.Or(inner));
+
+        } else if (key === 'NOT' && Array.isArray(value)) {
+            const inner = (value as WhereInput[]).flatMap(buildConditions);
+            if (inner.length > 0) conditions.push(LogicalOperator.Not(inner));
+
+        } else if (value === null || value === undefined) {
+            conditions.push(new FieldConditionBuilder(key).isNull());
+
+        } else if (typeof value === 'object' && !Array.isArray(value)) {
+            const isOpObject = Object.keys(value as object).some(k => OPERATOR_KEYS.has(k));
+
+            if (isOpObject) {
+                const f = value as FieldFilter;
+                const fcb = (k = key) => new FieldConditionBuilder(k);
+
+                // ── Equality ─────────────────────────────────────────────────
+                if (f.equals     !== undefined) conditions.push(fcb().equals(f.equals));
+                if (f.not        !== undefined) conditions.push(fcb().notEquals(f.not));
+                if (f.in         !== undefined) conditions.push(fcb().in(f.in));
+                if (f.notIn      !== undefined) conditions.push(fcb().notIn(f.notIn));
+                if (f.inDataset  !== undefined) conditions.push(fcb().inDataset(f.inDataset));
+
+                // ── Numeric / comparison ─────────────────────────────────────
+                if (f.lt         !== undefined) conditions.push(fcb().lessThan(f.lt));
+                if (f.lte        !== undefined) conditions.push(fcb().lessThanOrEqual(f.lte));
+                if (f.gt         !== undefined) conditions.push(fcb().greaterThan(f.gt));
+                if (f.gte        !== undefined) conditions.push(fcb().greaterThanOrEqual(f.gte));
+                if (f.between    !== undefined) conditions.push(fcb().between(f.between.from, f.between.to));
+
+                // ── String ───────────────────────────────────────────────────
+                if (f.contains                   !== undefined) conditions.push(fcb().contains(f.contains));
+                if (f.startsWith                 !== undefined) conditions.push(fcb().startsWith(f.startsWith));
+                if (f.endsWith                   !== undefined) conditions.push(fcb().endsWith(f.endsWith));
+                if (f.containsCaseInsensitive     !== undefined) conditions.push(fcb().includesCaseInsensitive(f.containsCaseInsensitive));
+                if (f.startsWithCaseInsensitive   !== undefined) conditions.push(fcb().startsWithCaseInsensitive(f.startsWithCaseInsensitive));
+                if (f.endsWithCaseInsensitive     !== undefined) conditions.push(fcb().endsWithCaseInsensitive(f.endsWithCaseInsensitive));
+                if (f.regex                      !== undefined) conditions.push(fcb().regExpMatches(f.regex));
+
+                // ── Presence ─────────────────────────────────────────────────
+                if (f.isNotNull) conditions.push(fcb().isNotNull());
+                if (f.exists === true)  conditions.push(fcb().exists());
+                if (f.exists === false) conditions.push(fcb().notExists());
+
+                // ── IP ───────────────────────────────────────────────────────
+                if (f.isLocalIp)              conditions.push(fcb().isLocalIp());
+                if (f.isExternalIp)           conditions.push(fcb().isExternalIp());
+                if (f.inCountry !== undefined) conditions.push(fcb().inCountry(f.inCountry));
+                if (f.cidr      !== undefined) conditions.push(fcb().cidr(f.cidr));
+
+                // ── Misc ─────────────────────────────────────────────────────
+                if (f.keywords !== undefined) conditions.push(fcb().keywords(f.keywords));
+                if (f.b64      !== undefined) conditions.push(fcb().b64(f.b64));
+            } else {
+                // Shorthand object equality: { metadata: { role: 'admin' } }
+                conditions.push(new FieldConditionBuilder(key).equals(value));
+            }
+
+        } else {
+            // Primitive shorthand: { name: 'Alice', active: true }
+            conditions.push(new FieldConditionBuilder(key).equals(value));
+        }
+    }
+
+    return conditions;
+}
+
+function applyWhere(qb: QueryBuilder, where?: WhereInput, excludeDeletedKey?: string): QueryBuilder {
+    const conditions: LogicalOperator[] = [];
+
+    if (where && Object.keys(where).length > 0) {
+        conditions.push(...buildConditions(where));
+    }
+
+    if (excludeDeletedKey) {
+        conditions.push(new FieldConditionBuilder(excludeDeletedKey).notExists());
+    }
+
+    if (conditions.length === 0) return qb;
+    const op = conditions.length === 1 ? conditions[0] : LogicalOperator.And(conditions);
+    return qb.find(() => op);
+}
+
+function applySelect<T>(qb: QueryBuilder, select?: SelectInput<T>): QueryBuilder {
+    if (!select) return qb;
+    const fields = Object.entries(select)
+        .filter(([, v]) => v === true)
+        .map(([k]) => k);
+    return fields.length > 0 ? qb.selectFields(fields) : qb;
+}
+
+function buildAggregateSpec<T>(args: AggregateArgs<T>): AggregateSpec {
+    const spec: AggregateSpec = {};
+
+    if (args._count) {
+        spec['_count'] = { '$count': '*' };
+    }
+
+    const numericOps: Array<[keyof AggregateArgs, string]> = [
+        ['_sum', '$sum'],
+        ['_avg', '$avg'],
+        ['_min', '$min'],
+        ['_max', '$max'],
+    ];
+
+    for (const [argKey, scepterOp] of numericOps) {
+        const fields = args[argKey as keyof typeof args] as Record<string, boolean> | undefined;
+        if (!fields) continue;
+        for (const [field, enabled] of Object.entries(fields)) {
+            if (enabled) spec[`${argKey}_${field}`] = { [scepterOp]: field } as any;
+        }
+    }
+
+    return spec;
+}
+
+// ── ModelDelegate ─────────────────────────────────────────────────────────────
+
+export class ModelDelegate<T extends Record<string, any> = Record<string, any>> {
+    constructor(
+        private readonly client: OnDBClient,
+        private readonly collection: string
+    ) {}
+
+    private qb(): QueryBuilder {
+        return this.client.queryBuilder().collection(this.collection);
+    }
+
+    async findMany(args: FindManyArgs<T> = {}): Promise<T[]> {
+        const deletedKey = args.excludeDeleted === true ? 'deletedAt'
+            : typeof args.excludeDeleted === 'string' ? args.excludeDeleted
+            : undefined;
+        let qb = applyWhere(this.qb(), args.where, deletedKey);
+        qb = applySelect(qb, args.select);
+        if (args.orderBy) {
+            const [field, dir] = Object.entries(args.orderBy)[0];
+            qb = qb.sortBy(field, dir as 'asc' | 'desc');
+        }
+        if (args.take !== undefined) qb = qb.limit(args.take);
+        if (args.skip !== undefined) qb = qb.offset(args.skip);
+        const result = await qb.execute<T>();
+        return result.records ?? [];
+    }
+
+    async findFirst(args: FindFirstArgs<T> = {}): Promise<T | null> {
+        const results = await this.findMany({ ...args, take: 1 });
+        return results[0] ?? null;
+    }
+
+    async findUnique(args: FindUniqueArgs<T>): Promise<T | null> {
+        return this.findFirst(args);
+    }
+
+    async create(args: CreateArgs<T>): Promise<StoreResponse> {
+        return this.client.store({
+            collection: this.collection,
+            data: [args.data as Record<string, any>],
+        });
+    }
+
+    /** Sends all records in a single store call — not N round-trips. */
+    async createMany(args: CreateManyArgs<T>): Promise<StoreResponse> {
+        return this.client.store({
+            collection: this.collection,
+            data: args.data as Record<string, any>[],
+        });
+    }
+
+    /**
+     * Update a document by finding it with `identifierFind`, merging `patch` on top,
+     * and storing the result. OnDB deduplicates on unique fields, so this effectively
+     * replaces the existing record.
+     *
+     * @throws if no document matches `identifierFind`
+     */
+    async updateDocument(identifierFind: WhereInput<T>, patch: Partial<T>): Promise<StoreResponse> {
+        const existing = await this.findFirst({ where: identifierFind });
+        if (!existing) throw new Error(`updateDocument: no document found matching the identifier`);
+        return this.client.store({
+            collection: this.collection,
+            data: [{ ...existing, ...patch }],
+        });
+    }
+
+    /**
+     * Soft-delete a document by finding it with `identifierFind` and storing it back
+     * with `deletedAt: Date.now()` (plus any optional extra `patch`).
+     * OnDB deduplicates on unique fields, so this effectively marks the record as deleted.
+     *
+     * @throws if no document matches `identifierFind`
+     */
+    async deleteDocument(identifierFind: WhereInput<T>, patch?: Partial<T>): Promise<StoreResponse> {
+        const existing = await this.findFirst({ where: identifierFind });
+        if (!existing) throw new Error(`deleteDocument: no document found matching the identifier`);
+        return this.client.store({
+            collection: this.collection,
+            data: [{ ...existing, deletedAt: Date.now(), ...(patch ?? {}) }],
+        });
+    }
+
+    async count(args: CountArgs<T> = {}): Promise<number> {
+        return applyWhere(this.qb(), args.where).count();
+    }
+
+    /**
+     * Aggregate result keys follow the pattern: `_count`, `_sum_<field>`, `_avg_<field>`, etc.
+     * @example
+     * const result = await db.model('users').aggregate({
+     *   where: { active: true },
+     *   _count: true,
+     *   _avg: { age: true },
+     *   _sum: { balance: true },
+     * });
+     * // result: { _count: 42, _avg_age: 28.5, _sum_balance: 99000 }
+     */
+    async aggregate(args: AggregateArgs<T>): Promise<Record<string, any>> {
+        const qb = applyWhere(this.qb(), args.where);
+        return qb.runAggregate(buildAggregateSpec(args));
+    }
+}

package/src/query-sdk/QueryBuilder.ts

@@ -80,12 +80,13 @@ export class QueryBuilder {
         return new WhereClause(this, fieldName);
     }
 
-    // Server-side JOIN with Scepter query engine (RECOMMENDED)
-    // This generates a JOIN query that the backend executes recursively
-    serverJoin(alias: string, model: string, resolve: { find?: any; select?: SelectionMap }): QueryBuilder {
+    // Server-side JOIN with Scepter query engine (low-level)
+    // many: true → array result (joinMany), false → single object (joinOne), undefined → Scepter default
+    serverJoin(alias: string, model: string, resolve: { find?: any; select?: SelectionMap }, many?: boolean): QueryBuilder {
         this.serverJoinConfigs.push({
             alias,
             model,
+            many,
             resolve
         });
         return this;

package/src/query-sdk/tests/Joins.test.ts

@@ -0,0 +1,154 @@
+import { QueryBuilder } from '../index';
+import { MockHttpClient } from './setup';
+
+const APP = 'test_app';
+
+describe('Join wire format — getQueryRequest() equality', () => {
+    function builder() {
+        return new QueryBuilder(new MockHttpClient(), 'http://localhost:9092', APP);
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // joinWith  ≡  serverJoin (no many)
+    // ─────────────────────────────────────────────────────────────────────────
+
+    test('joinWith produces identical request to serverJoin', () => {
+        const withServerJoin = builder()
+            .collection('tweets')
+            .serverJoin('author', 'users', {
+                find: { address: { is: '$data.author' } },
+                select: { display_name: true, avatar_url: true },
+            })
+            .getQueryRequest();
+
+        const withJoinWith = builder()
+            .collection('tweets')
+            .joinWith('author', 'users')
+                .onField('address').equals('$data.author')
+                .selectFields(['display_name', 'avatar_url'])
+                .build()
+            .getQueryRequest();
+
+        expect(withJoinWith).toEqual(withServerJoin);
+    });
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // joinOne  ≡  serverJoin(…, false)
+    // ─────────────────────────────────────────────────────────────────────────
+
+    test('joinOne produces identical request to serverJoin with many=false', () => {
+        const withServerJoin = builder()
+            .collection('tweets')
+            .serverJoin('author', 'users', {
+                find: { address: { is: '$data.author' } },
+                select: { display_name: true, avatar_url: true },
+            }, false)
+            .getQueryRequest();
+
+        const withJoinOne = builder()
+            .collection('tweets')
+            .joinOne('author', 'users')
+                .onField('address').equals('$data.author')
+                .selectFields(['display_name', 'avatar_url'])
+                .build()
+            .getQueryRequest();
+
+        expect(withJoinOne).toEqual(withServerJoin);
+    });
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // joinMany  ≡  serverJoin(…, true)
+    // ─────────────────────────────────────────────────────────────────────────
+
+    test('joinMany produces identical request to serverJoin with many=true', () => {
+        const withServerJoin = builder()
+            .collection('users')
+            .serverJoin('tweets', 'tweets', {
+                find: { author: { is: '$data.address' } },
+                select: { id: true, content: true, created_at: true },
+            }, true)
+            .getQueryRequest();
+
+        const withJoinMany = builder()
+            .collection('users')
+            .joinMany('tweets', 'tweets')
+                .onField('author').equals('$data.address')
+                .selectFields(['id', 'content', 'created_at'])
+                .build()
+            .getQueryRequest();
+
+        expect(withJoinMany).toEqual(withServerJoin);
+    });
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Multiple joins
+    // ─────────────────────────────────────────────────────────────────────────
+
+    test('multiple joins: serverJoin chain equals joinOne + joinMany chain', () => {
+        const withServerJoin = builder()
+            .collection('tweets')
+            .serverJoin('author', 'users', {
+                find: { address: { is: '$data.author' } },
+                select: { display_name: true },
+            }, false)
+            .serverJoin('likes', 'likes', {
+                find: { tweet_id: { is: '$data.id' } },
+                select: { user: true },
+            }, true)
+            .getQueryRequest();
+
+        const withFluent = builder()
+            .collection('tweets')
+            .joinOne('author', 'users')
+                .onField('address').equals('$data.author')
+                .selectFields(['display_name'])
+                .build()
+            .joinMany('likes', 'likes')
+                .onField('tweet_id').equals('$data.id')
+                .selectFields(['user'])
+                .build()
+            .getQueryRequest();
+
+        expect(withFluent).toEqual(withServerJoin);
+    });
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Joins + whereField
+    // ─────────────────────────────────────────────────────────────────────────
+
+    test('joins combined with whereField: serverJoin equals joinOne', () => {
+        const withServerJoin = builder()
+            .collection('tweets')
+            .whereField('reply_to_id').isNull()
+            .serverJoin('author', 'users', {
+                find: { address: { is: '$data.author' } },
+                select: {},
+            }, false)
+            .getQueryRequest();
+
+        const withJoinOne = builder()
+            .collection('tweets')
+            .whereField('reply_to_id').isNull()
+            .joinOne('author', 'users')
+                .onField('address').equals('$data.author')
+                .build()
+            .getQueryRequest();
+
+        expect(withJoinOne).toEqual(withServerJoin);
+    });
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // getQueryRequest() includes root; buildRawQuery() does not
+    // ─────────────────────────────────────────────────────────────────────────
+
+    test('getQueryRequest includes root, buildRawQuery does not', () => {
+        const qb = builder()
+            .collection('tweets')
+            .joinOne('author', 'users')
+                .onField('address').equals('$data.author')
+                .build();
+
+        expect(qb.getQueryRequest().root).toBe(`${APP}::tweets`);
+        expect((qb.buildRawQuery() as any).root).toBeUndefined();
+    });
+});