@spooky-sync/query-builder 0.0.1-canary.38 → 0.0.1-canary.381

package/src/query-builder.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, expectTypeOf } from 'vitest';
 import { QueryBuilder, buildQueryFromOptions } from './query-builder';
 import { RecordId } from 'surrealdb';
-import type { TableModel } from './table-schema';
+import type { ChannelTableNames, TableModel } from './table-schema';
 
 // Schema for testing the new array-based API
 const testSchema = {
@@ -92,6 +92,84 @@ describe('QueryBuilder', () => {
     });
   });
 
+  it('should build a comparison operator condition via { _op, _val }', () => {
+    const builder = new QueryBuilder(testSchema, 'user', (q) => q.selectQuery);
+    builder.where({ created_at: { _op: '<=', _val: 5 } });
+    const result = builder.build().run();
+
+    expect(result.query).toBe('SELECT * FROM user WHERE created_at <= $created_at;');
+    expect(result.vars).toEqual({ created_at: 5 });
+  });
+
+  it('should build an OR group via _or with position-indexed params', () => {
+    const builder = new QueryBuilder(testSchema, 'user', (q) => q.selectQuery);
+    builder.where({ _or: [{ username: 'x' }, { email: 'x' }] });
+    const result = builder.build().run();
+
+    expect(result.query).toBe(
+      'SELECT * FROM user WHERE (username = $username__or0 OR email = $email__or1);'
+    );
+    expect(result.vars).toEqual({ username__or0: 'x', email__or1: 'x' });
+  });
+
+  it('should not collide an _or branch with a top-level condition on the same field', () => {
+    // Mirrors the game filter where a color filter (white = me) coexists with an
+    // opponent OR on white/black: the OR branch must use its own param name.
+    const builder = new QueryBuilder(testSchema, 'user', (q) => q.selectQuery);
+    builder.where({ username: 'me', _or: [{ username: 'opp' }, { email: 'opp' }] });
+    const result = builder.build().run();
+
+    expect(result.query).toBe(
+      'SELECT * FROM user WHERE username = $username AND ' +
+        '(username = $username__or0 OR email = $email__or1);'
+    );
+    expect(result.vars).toEqual({ username: 'me', username__or0: 'opp', email__or1: 'opp' });
+  });
+
+  it('should combine equality + comparison + OR group + order/limit/offset', () => {
+    // The shape the filtered game list produces: scope equality, a date floor as
+    // an integer sort_index comparison, an opponent OR group, paginated.
+    const builder = new QueryBuilder(testSchema, 'user', (q) => q.selectQuery);
+    builder
+      .where({ email: 'e', created_at: { _op: '<=', _val: 5 }, _or: [{ username: 'p' }, { email: 'p' }] })
+      .orderBy('created_at', 'asc')
+      .limit(50)
+      .offset(0);
+    const result = builder.build().run();
+
+    expect(result.query).toBe(
+      'SELECT * FROM user WHERE email = $email AND created_at <= $created_at AND ' +
+        '(username = $username__or0 OR email = $email__or1) ORDER BY created_at asc LIMIT 50 START 0;'
+    );
+    expect(result.vars).toEqual({
+      email: 'e',
+      created_at: 5,
+      username__or0: 'p',
+      email__or1: 'p',
+    });
+  });
+
+  it('should produce a stable hash for the same logical filtered query', () => {
+    const make = () =>
+      new QueryBuilder(testSchema, 'user', (q) => q.selectQuery)
+        .where({ email: 'e', _or: [{ username: 'p' }, { email: 'p' }] })
+        .orderBy('created_at', 'asc')
+        .limit(50)
+        .offset(0)
+        .build()
+        .run();
+    expect(make().hash).toBe(make().hash);
+
+    const different = new QueryBuilder(testSchema, 'user', (q) => q.selectQuery)
+      .where({ email: 'e', _or: [{ username: 'q' }, { email: 'q' }] })
+      .orderBy('created_at', 'asc')
+      .limit(50)
+      .offset(0)
+      .build()
+      .run();
+    expect(different.hash).not.toBe(make().hash);
+  });
+
   it('should build query with select fields', () => {
     const builder = new QueryBuilder(testSchema, 'user', (q) => q.selectQuery);
     builder.select('username', 'email');
@@ -181,6 +259,23 @@ describe('Relationship Queries', () => {
       'SELECT *, (SELECT *, (SELECT * FROM user WHERE id=$parent.author LIMIT 1)[0] AS author FROM comment WHERE thread=$parent.id) AS comments FROM thread;'
     );
   });
+
+  // An unknown relationship (e.g. a table owned by a devOnly backend that a
+  // free/Cloudflare deployment never provisions, so codegen drops it from the
+  // client schema) must be SKIPPED, not throw — otherwise it takes the whole
+  // query (and its other `.related()` siblings) down. This is what left the
+  // ThreadDetail page stuck on "Loading..." when `jobs` disappeared.
+  it('skips an unknown relationship instead of throwing', () => {
+    const builder = new QueryBuilder(testSchema, 'thread', (q) => q.selectQuery);
+    expect(() => {
+      builder.related('author' as any);
+      builder.related('does_not_exist' as any); // must NOT throw
+    }).not.toThrow();
+    const result = builder.build().run();
+    // The valid relation is still projected; the unknown one is simply absent.
+    expect(result.query).toContain('AS author');
+    expect(result.query).not.toContain('does_not_exist');
+  });
 });
 
 describe('buildQueryFromOptions', () => {
@@ -215,6 +310,28 @@ describe('buildQueryFromOptions', () => {
 
     expect(result.query).toBe('LIVE SELECT * FROM user WHERE username = $username;');
   });
+
+  // Regression guard for the thread-detail "crossed results → 404" bug: the
+  // engine-neutral plan's top-level WHERE must reference the SAME var the surql
+  // binds (`$username`), so materialization (`select(plan, params)`) filters by
+  // the query's own `params` (its identity) instead of a baked literal that
+  // could belong to another query's plan. So the top-level plan node must carry
+  // `paramRef` equal to the surql var name.
+  it('top-level plan WHERE uses paramRef matching the surql var (slaved to params)', () => {
+    const result = buildQueryFromOptions<TableModel<(typeof testSchema)['tables'][0]>, boolean>(
+      'SELECT',
+      'user',
+      { where: { username: 'john' } },
+      testSchema
+    );
+    // surql binds $username …
+    expect(result.query).toBe('SELECT * FROM user WHERE username = $username;');
+    expect(result.vars).toEqual({ username: 'john' });
+    // … and the plan references that same var, not just a baked literal.
+    expect(result.plan?.where).toEqual([
+      { field: 'username', op: '=', value: 'john', paramRef: 'username' },
+    ]);
+  });
 });
 
 describe('RecordId Parsing', () => {
@@ -469,3 +586,142 @@ describe('Subquery Filtering', () => {
     );
   });
 });
+
+// An `-- @opaque` column is synced to the client but never stored server-side,
+// so nothing on the server can evaluate a predicate against it. The failure mode
+// without a guard is silent and asymmetric: the LOCAL cache does hold the value,
+// so the clause filters correctly on screen while the server-side membership set
+// it is reconciled against was computed without it — rows appear and vanish
+// instead of erroring. Fail at the call site instead.
+const opaqueSchema = {
+  tables: [
+    {
+      name: 'document' as const,
+      columns: {
+        id: { type: 'string' as const, optional: false },
+        title: { type: 'string' as const, optional: false },
+        thumbnail: {
+          type: 'Uint8Array' as const,
+          optional: true,
+          bytes: true,
+          opaque: true,
+        },
+        meta: { type: 'json' as const, optional: true, opaque: true },
+      },
+      primaryKey: ['id'] as const,
+    },
+  ],
+  relationships: [],
+  backends: {},
+} as const;
+
+describe('@opaque column guards', () => {
+  const qb = () => new QueryBuilder(opaqueSchema, 'document');
+
+  it('rejects an opaque column in where()', () => {
+    expect(() => qb().where({ thumbnail: null } as never)).toThrow(/thumbnail/);
+    expect(() => qb().where({ thumbnail: null } as never)).toThrow(/@opaque/);
+  });
+
+  it('rejects an opaque column used with a comparison operator object', () => {
+    expect(() =>
+      qb().where({ thumbnail: { _op: '!=', _val: null } } as never)
+    ).toThrow(/@opaque/);
+  });
+
+  it('rejects an opaque column inside an _or branch', () => {
+    expect(() =>
+      qb().where({
+        _or: [{ title: 'a' }, { thumbnail: null }],
+      } as never)
+    ).toThrow(/thumbnail/);
+  });
+
+  it('rejects a nested path rooted at an opaque column', () => {
+    expect(() => qb().where({ 'meta.secret': 'x' } as never)).toThrow(/@opaque/);
+  });
+
+  it('rejects an opaque column in orderBy()', () => {
+    expect(() => qb().orderBy('thumbnail' as never)).toThrow(/@opaque/);
+  });
+
+  it('allows a normal column in where() and orderBy()', () => {
+    expect(() => qb().where({ title: 'a' }).orderBy('title')).not.toThrow();
+  });
+
+  it('allows selecting an opaque column', () => {
+    // Projection is the whole point of @opaque: the value IS delivered, the
+    // client just cannot ask the server to filter on it.
+    expect(() => qb().select('id', 'thumbnail' as never)).not.toThrow();
+  });
+
+  it('does not reject an opaque column name on a different table', () => {
+    // The flag is per (table, column); names are not globally unique.
+    const multi = {
+      tables: [
+        ...opaqueSchema.tables,
+        {
+          name: 'other' as const,
+          columns: {
+            id: { type: 'string' as const, optional: false },
+            thumbnail: { type: 'string' as const, optional: false },
+          },
+          primaryKey: ['id'] as const,
+        },
+      ],
+      relationships: [],
+      backends: {},
+    } as const;
+    expect(() =>
+      new QueryBuilder(multi, 'other').where({ thumbnail: 'x' } as never)
+    ).not.toThrow();
+  });
+});
+
+// `-- @channel` tables accept `.channel(peers)`; `-- @ephemeral` columns only
+// travel between peers, so the server can never filter on them.
+const channelSchema = {
+  tables: [
+    {
+      name: 'call' as const,
+      columns: {
+        id: { type: 'string' as const, optional: false, recordId: true },
+        caller: { type: 'string' as const, optional: false, recordId: true },
+        callee: { type: 'string' as const, optional: false, recordId: true },
+        view_pos: { type: 'string' as const, optional: true, ephemeral: true },
+      },
+      channel: true as const,
+      primaryKey: ['id'] as const,
+    },
+    {
+      name: 'note' as const,
+      columns: {
+        id: { type: 'string' as const, optional: false, recordId: true },
+        title: { type: 'string' as const, optional: false },
+      },
+      primaryKey: ['id'] as const,
+    },
+  ],
+  relationships: [],
+  backends: {},
+} as const;
+
+describe('channel schema', () => {
+  it('rejects an ephemeral column in where() and orderBy()', () => {
+    expect(() => new QueryBuilder(channelSchema, 'call').where({ view_pos: '1' } as never)).toThrow(/@ephemeral/);
+    expect(() => new QueryBuilder(channelSchema, 'call').orderBy('view_pos' as never)).toThrow(/@ephemeral/);
+  });
+
+  it('ignoreUnusedArgs marks the query without changing it', () => {
+    const plain = new QueryBuilder(channelSchema, 'call').limit(5).build();
+    const marked = new QueryBuilder(channelSchema, 'call').limit(5).ignoreUnusedArgs().build();
+    expect(plain.ignoresUnusedArgs).toBe(false);
+    expect(marked.ignoresUnusedArgs).toBe(true);
+    expect(marked.hash).toBe(plain.hash);
+    expect(marked.innerQuery.selectQuery.query).toBe(plain.innerQuery.selectQuery.query);
+  });
+
+  it('names the channel tables', () => {
+    expectTypeOf<ChannelTableNames<typeof channelSchema>>().toEqualTypeOf<'call'>();
+  });
+});