@opensaas/stack-core 0.19.0 → 0.20.0

package/dist/query/index.test.js

@@ -0,0 +1,632 @@
+import { describe, it, expect, vi } from 'vitest';
+import { defineFragment, runQuery, runQueryOne, buildInclude, pickFields, isFragment, } from './index.js';
+// ─────────────────────────────────────────────────────────────
+// Helpers for building a fake context.db delegate
+// ─────────────────────────────────────────────────────────────
+function makeDelegate(rows, findFirstRow) {
+    return {
+        findMany: vi.fn(async (_args) => rows),
+        findFirst: vi.fn(async (_args) => findFirstRow ?? rows[0] ?? null),
+    };
+}
+function makeContext(delegates) {
+    return { db: delegates };
+}
+// ─────────────────────────────────────────────────────────────
+// defineFragment — construction
+// ─────────────────────────────────────────────────────────────
+describe('defineFragment', () => {
+    it('returns an object with _type: "fragment" and the field selection', () => {
+        const frag = defineFragment()({ id: true, name: true });
+        expect(frag._type).toBe('fragment');
+        expect(frag._fields).toEqual({ id: true, name: true });
+    });
+    it('accepts true for all field types', () => {
+        const frag = defineFragment()({
+            id: true,
+            title: true,
+            content: true,
+            published: true,
+            createdAt: true,
+            authorId: true,
+        });
+        expect(Object.keys(frag._fields)).toEqual([
+            'id',
+            'title',
+            'content',
+            'published',
+            'createdAt',
+            'authorId',
+        ]);
+    });
+    it('accepts a nested fragment for a relationship field', () => {
+        const userFrag = defineFragment()({ id: true, name: true });
+        const postFrag = defineFragment()({ id: true, author: userFrag });
+        expect(postFrag._fields.author).toBe(userFrag);
+    });
+    it('accepts a nested fragment for a many relationship', () => {
+        const tagFrag = defineFragment()({ id: true, name: true });
+        const postFrag = defineFragment()({ id: true, tags: tagFrag });
+        expect(postFrag._fields.tags).toBe(tagFrag);
+    });
+});
+// ─────────────────────────────────────────────────────────────
+// ResultOf — static type tests (compile-time checks)
+// ─────────────────────────────────────────────────────────────
+describe('ResultOf (type-level checks)', () => {
+    it('scalar fragment produces a plain picked type', () => {
+        const frag = defineFragment()({ id: true, name: true, email: true });
+        const r = { id: '1', name: 'Alice', email: 'a@test.com' };
+        expect(r).toBeTruthy();
+        expect(frag._type).toBe('fragment');
+    });
+    it('nullable scalar fields are preserved', () => {
+        const frag = defineFragment()({ id: true, content: true });
+        // content should be string | null
+        const r = { id: '1', content: null };
+        expect(r.content).toBeNull();
+        expect(frag._type).toBe('fragment');
+    });
+    it('nested fragment on a nullable relationship preserves null', () => {
+        const userFrag = defineFragment()({ id: true, name: true });
+        const postFrag = defineFragment()({ id: true, author: userFrag });
+        // author should be { id: string; name: string } | null
+        const r = { id: '1', author: null };
+        expect(r.author).toBeNull();
+        expect(postFrag._type).toBe('fragment');
+    });
+    it('nested fragment on a many relationship produces an array', () => {
+        const tagFrag = defineFragment()({ id: true, name: true });
+        const postFrag = defineFragment()({ id: true, tags: tagFrag });
+        const r = { id: '1', tags: [{ id: 't1', name: 'ts' }] };
+        expect(r.tags).toHaveLength(1);
+        expect(postFrag._type).toBe('fragment');
+    });
+    it('deep nesting (comment → post → author) resolves correctly', () => {
+        const userFrag = defineFragment()({ id: true, name: true });
+        const postFrag = defineFragment()({ id: true, title: true, author: userFrag });
+        const commentFrag = defineFragment()({
+            id: true,
+            body: true,
+            post: postFrag,
+        });
+        const r = {
+            id: 'c1',
+            body: 'hi',
+            post: {
+                id: 'p1',
+                title: 'Hello',
+                author: { id: 'u1', name: 'Alice' },
+            },
+        };
+        expect(r.post?.author?.name).toBe('Alice');
+        expect(commentFrag._type).toBe('fragment');
+    });
+});
+// ─────────────────────────────────────────────────────────────
+// runQuery — runtime behaviour
+// ─────────────────────────────────────────────────────────────
+describe('runQuery', () => {
+    const userFrag = defineFragment()({ id: true, name: true, email: true });
+    const rawUsers = [
+        { id: 'u1', name: 'Alice', email: 'alice@test.com', role: 'admin', bio: null },
+        { id: 'u2', name: 'Bob', email: 'bob@test.com', role: 'user', bio: 'Hey there' },
+    ];
+    it('calls context.db[dbKey].findMany with no args when none supplied', async () => {
+        const delegate = makeDelegate(rawUsers);
+        const ctx = makeContext({ user: delegate });
+        await runQuery(ctx, 'User', userFrag);
+        expect(delegate.findMany).toHaveBeenCalledWith(undefined);
+    });
+    it('returns only the fields specified in the fragment', async () => {
+        const ctx = makeContext({ user: makeDelegate(rawUsers) });
+        const results = await runQuery(ctx, 'User', userFrag);
+        expect(results).toHaveLength(2);
+        // Only id, name, email — not role or bio
+        expect(results[0]).toEqual({ id: 'u1', name: 'Alice', email: 'alice@test.com' });
+        expect(results[1]).toEqual({ id: 'u2', name: 'Bob', email: 'bob@test.com' });
+        expect(results[0]).not.toHaveProperty('role');
+        expect(results[0]).not.toHaveProperty('bio');
+    });
+    it('passes where, orderBy, take, skip to findMany', async () => {
+        const delegate = makeDelegate(rawUsers);
+        const ctx = makeContext({ user: delegate });
+        await runQuery(ctx, 'User', userFrag, {
+            where: { role: 'admin' },
+            orderBy: { name: 'asc' },
+            take: 5,
+            skip: 2,
+        });
+        expect(delegate.findMany).toHaveBeenCalledWith({
+            where: { role: 'admin' },
+            orderBy: { name: 'asc' },
+            take: 5,
+            skip: 2,
+        });
+    });
+    it('converts PascalCase listKey to camelCase for db access', async () => {
+        const delegate = makeDelegate([]);
+        const ctx = makeContext({ blogPost: delegate });
+        await runQuery(ctx, 'BlogPost', defineFragment()({ id: true }));
+        expect(delegate.findMany).toHaveBeenCalled();
+    });
+    it('returns an empty array when findMany returns nothing', async () => {
+        const ctx = makeContext({ user: makeDelegate([]) });
+        const results = await runQuery(ctx, 'User', userFrag);
+        expect(results).toEqual([]);
+    });
+    describe('with nested fragment (relationship)', () => {
+        const tagFrag = defineFragment()({ id: true, name: true });
+        const postFrag = defineFragment()({
+            id: true,
+            title: true,
+            author: userFrag,
+            tags: tagFrag,
+        });
+        const rawPosts = [
+            {
+                id: 'p1',
+                title: 'Hello World',
+                content: 'body',
+                published: true,
+                createdAt: new Date('2024-01-01'),
+                authorId: 'u1',
+                author: {
+                    id: 'u1',
+                    name: 'Alice',
+                    email: 'alice@test.com',
+                    role: 'admin',
+                    bio: null,
+                },
+                tags: [
+                    { id: 't1', name: 'TypeScript', slug: 'typescript' },
+                    { id: 't2', name: 'Node', slug: 'node' },
+                ],
+            },
+        ];
+        it('passes include for relationship fields to findMany', async () => {
+            const delegate = makeDelegate(rawPosts);
+            const ctx = makeContext({ post: delegate });
+            await runQuery(ctx, 'Post', postFrag);
+            expect(delegate.findMany).toHaveBeenCalledWith(expect.objectContaining({
+                include: { author: true, tags: true },
+            }));
+        });
+        it('picks only the selected nested fields', async () => {
+            const ctx = makeContext({ post: makeDelegate(rawPosts) });
+            const results = await runQuery(ctx, 'Post', postFrag);
+            expect(results[0].author).toEqual({ id: 'u1', name: 'Alice', email: 'alice@test.com' });
+            // role and bio are NOT selected in userFrag
+            expect(results[0].author).not.toHaveProperty('role');
+            expect(results[0].author).not.toHaveProperty('bio');
+        });
+        it('maps tag arrays and strips unselected fields', async () => {
+            const ctx = makeContext({ post: makeDelegate(rawPosts) });
+            const results = await runQuery(ctx, 'Post', postFrag);
+            // slug is not in tagFrag, so it must be absent
+            expect(results[0].tags[0]).not.toHaveProperty('slug');
+            expect(results[0].tags[0]).toEqual({ id: 't1', name: 'TypeScript' });
+            expect(results[0].tags[1]).toEqual({ id: 't2', name: 'Node' });
+        });
+    });
+    describe('with null relationship', () => {
+        it('preserves null for an unset relationship', async () => {
+            const authorFrag = defineFragment()({ id: true, name: true });
+            const postFrag = defineFragment()({ id: true, author: authorFrag });
+            const rawPost = {
+                id: 'p2',
+                title: 'Draft',
+                content: null,
+                published: false,
+                createdAt: new Date(),
+                authorId: null,
+                author: null,
+                tags: [],
+            };
+            const ctx = makeContext({ post: makeDelegate([rawPost]) });
+            const results = await runQuery(ctx, 'Post', postFrag);
+            expect(results[0].author).toBeNull();
+        });
+    });
+    describe('deeply nested (three levels)', () => {
+        it('recursively builds include and picks fields', async () => {
+            const authorFrag = defineFragment()({ id: true, name: true });
+            const postFrag = defineFragment()({
+                id: true,
+                title: true,
+                author: authorFrag,
+            });
+            const commentFrag = defineFragment()({
+                id: true,
+                body: true,
+                post: postFrag,
+            });
+            const raw = [
+                {
+                    id: 'c1',
+                    body: 'Nice post!',
+                    post: {
+                        id: 'p1',
+                        title: 'Hello',
+                        content: 'body',
+                        published: true,
+                        createdAt: new Date(),
+                        authorId: 'u1',
+                        author: { id: 'u1', name: 'Alice', email: 'a@t.com', role: 'user', bio: null },
+                        tags: [],
+                    },
+                    author: null,
+                },
+            ];
+            const delegate = makeDelegate(raw);
+            const ctx = makeContext({ comment: delegate });
+            const results = await runQuery(ctx, 'Comment', commentFrag);
+            // include passed to findMany
+            expect(delegate.findMany).toHaveBeenCalledWith(expect.objectContaining({
+                include: {
+                    post: { include: { author: true } },
+                },
+            }));
+            // result shape
+            expect(results[0]).toEqual({
+                id: 'c1',
+                body: 'Nice post!',
+                post: {
+                    id: 'p1',
+                    title: 'Hello',
+                    author: { id: 'u1', name: 'Alice' },
+                },
+            });
+        });
+    });
+});
+// ─────────────────────────────────────────────────────────────
+// runQueryOne — runtime behaviour
+// ─────────────────────────────────────────────────────────────
+describe('runQueryOne', () => {
+    const userFrag = defineFragment()({ id: true, name: true, email: true });
+    const rawUser = {
+        id: 'u1',
+        name: 'Alice',
+        email: 'alice@test.com',
+        role: 'admin',
+        bio: null,
+    };
+    it('calls context.db[dbKey].findFirst with the where clause', async () => {
+        const delegate = makeDelegate([rawUser], rawUser);
+        const ctx = makeContext({ user: delegate });
+        await runQueryOne(ctx, 'User', userFrag, { id: 'u1' });
+        expect(delegate.findFirst).toHaveBeenCalledWith({ where: { id: 'u1' } });
+    });
+    it('returns only the fields specified in the fragment', async () => {
+        const ctx = makeContext({ user: makeDelegate([rawUser], rawUser) });
+        const result = await runQueryOne(ctx, 'User', userFrag, { id: 'u1' });
+        expect(result).toEqual({ id: 'u1', name: 'Alice', email: 'alice@test.com' });
+        expect(result).not.toHaveProperty('role');
+        expect(result).not.toHaveProperty('bio');
+    });
+    it('returns null when findFirst returns null', async () => {
+        const delegate = makeDelegate([], null);
+        const ctx = makeContext({ user: delegate });
+        const result = await runQueryOne(ctx, 'User', userFrag, { id: 'nope' });
+        expect(result).toBeNull();
+    });
+    it('returns null when findFirst returns undefined', async () => {
+        const delegate = {
+            findMany: vi.fn(async () => []),
+            findFirst: vi.fn(async () => null),
+        };
+        const ctx = makeContext({ user: delegate });
+        const result = await runQueryOne(ctx, 'User', userFrag, { id: 'nope' });
+        expect(result).toBeNull();
+    });
+    it('passes include for relationship fields to findFirst', async () => {
+        const authorFrag = defineFragment()({ id: true, name: true });
+        const postFrag = defineFragment()({ id: true, title: true, author: authorFrag });
+        const rawPost = {
+            id: 'p1',
+            title: 'Hello',
+            content: null,
+            published: true,
+            createdAt: new Date(),
+            authorId: 'u1',
+            author: { id: 'u1', name: 'Alice', email: 'a@t.com', role: 'user', bio: null },
+            tags: [],
+        };
+        const delegate = makeDelegate([rawPost], rawPost);
+        const ctx = makeContext({ post: delegate });
+        const result = await runQueryOne(ctx, 'Post', postFrag, { id: 'p1' });
+        expect(delegate.findFirst).toHaveBeenCalledWith({
+            where: { id: 'p1' },
+            include: { author: true },
+        });
+        expect(result).toEqual({
+            id: 'p1',
+            title: 'Hello',
+            author: { id: 'u1', name: 'Alice' },
+        });
+    });
+    it('converts PascalCase listKey to camelCase', async () => {
+        const delegate = makeDelegate([], null);
+        const ctx = makeContext({ blogPost: delegate });
+        await runQueryOne(ctx, 'BlogPost', defineFragment()({ id: true }), {
+            id: 'p1',
+        });
+        expect(delegate.findFirst).toHaveBeenCalled();
+    });
+});
+// ─────────────────────────────────────────────────────────────
+// Fragment composition — reusability
+// ─────────────────────────────────────────────────────────────
+describe('fragment composition', () => {
+    it('the same fragment can be reused in multiple parent fragments', async () => {
+        const userFrag = defineFragment()({ id: true, name: true });
+        const postFrag = defineFragment()({ id: true, author: userFrag });
+        const commentFrag = defineFragment()({ id: true, author: userFrag });
+        // Both refer to the exact same userFrag instance
+        expect(postFrag._fields.author).toBe(userFrag);
+        expect(commentFrag._fields.author).toBe(userFrag);
+    });
+    it('composes three levels deep without mutation', async () => {
+        const userFrag = defineFragment()({ id: true, name: true });
+        const postFrag = defineFragment()({
+            id: true,
+            title: true,
+            author: userFrag,
+        });
+        const commentFrag = defineFragment()({
+            id: true,
+            body: true,
+            post: postFrag,
+        });
+        // Verify structure without executing any query
+        expect(commentFrag._type).toBe('fragment');
+        const postFieldInComment = commentFrag._fields.post;
+        expect(postFieldInComment._type).toBe('fragment');
+        const authorFieldInPost = postFieldInComment._fields.author;
+        expect(authorFieldInPost._fields).toEqual({ id: true, name: true });
+    });
+});
+// ─────────────────────────────────────────────────────────────
+// isFragment — runtime guard
+// ─────────────────────────────────────────────────────────────
+describe('isFragment', () => {
+    it('returns true for a fragment created by defineFragment', () => {
+        const frag = defineFragment()({ id: true });
+        expect(isFragment(frag)).toBe(true);
+    });
+    it('returns false for a RelationSelector object', () => {
+        const frag = defineFragment()({ id: true });
+        const selector = { query: frag, where: { active: true } };
+        expect(isFragment(selector)).toBe(false);
+    });
+    it('returns false for primitives and null', () => {
+        expect(isFragment(true)).toBe(false);
+        expect(isFragment(null)).toBe(false);
+        expect(isFragment(undefined)).toBe(false);
+        expect(isFragment('fragment')).toBe(false);
+        expect(isFragment(42)).toBe(false);
+    });
+    it('returns false for a plain object without _type', () => {
+        expect(isFragment({ id: true })).toBe(false);
+    });
+});
+describe('buildInclude with RelationSelector', () => {
+    it('generates a simple include for a shorthand fragment', () => {
+        const userFrag = defineFragment()({ id: true, name: true });
+        const postFrag = defineFragment()({ id: true, author: userFrag });
+        const result = buildInclude(postFrag._fields);
+        expect(result).toEqual({ author: true });
+    });
+    it('generates a where-filtered include for a RelationSelector', () => {
+        const commentFrag = defineFragment()({ id: true, body: true });
+        const postFrag = defineFragment()({
+            id: true,
+            comments: {
+                query: commentFrag,
+                where: { approved: true },
+            },
+        });
+        const result = buildInclude(postFrag._fields);
+        expect(result).toEqual({
+            comments: { where: { approved: true } },
+        });
+    });
+    it('includes orderBy, take and skip in the nested include', () => {
+        const commentFrag = defineFragment()({ id: true });
+        const postFrag = defineFragment()({
+            id: true,
+            comments: {
+                query: commentFrag,
+                where: { approved: true },
+                orderBy: { id: 'asc' },
+                take: 5,
+                skip: 10,
+            },
+        });
+        const result = buildInclude(postFrag._fields);
+        expect(result).toEqual({
+            comments: {
+                where: { approved: true },
+                orderBy: { id: 'asc' },
+                take: 5,
+                skip: 10,
+            },
+        });
+    });
+    it('combines RelationSelector args with a nested include from the inner fragment', () => {
+        const userFrag = defineFragment()({ id: true, name: true });
+        const commentWithAuthorFrag = defineFragment()({
+            id: true,
+            body: true,
+            author: userFrag,
+        });
+        const postFrag = defineFragment()({
+            id: true,
+            // Using RelationSelector with nested include (Comment has author)
+            author: {
+                query: defineFragment()({ id: true }),
+                where: { role: 'admin' },
+            },
+        });
+        const result = buildInclude(postFrag._fields);
+        // author has where clause (no nested include needed since User scalar fields)
+        expect(result).toEqual({
+            author: { where: { role: 'admin' } },
+        });
+        // Separate test: RelationSelector where inner fragment has nested relationships
+        const commentSelector = defineFragment()({
+            id: true,
+            author: userFrag,
+        });
+        const result2 = buildInclude(commentWithAuthorFrag._fields);
+        expect(result2).toEqual({ author: true });
+        // Suppress unused variable warning
+        expect(commentSelector._type).toBe('fragment');
+    });
+    it('returns undefined when there are no relationship fields', () => {
+        const frag = defineFragment()({ id: true, name: true, email: true });
+        const result = buildInclude(frag._fields);
+        expect(result).toBeUndefined();
+    });
+});
+// ─────────────────────────────────────────────────────────────
+// pickFields — RelationSelector branch
+// ─────────────────────────────────────────────────────────────
+describe('pickFields with RelationSelector', () => {
+    it('picks fields from a nested array using RelationSelector', () => {
+        const commentFrag = defineFragment()({ id: true, body: true });
+        const postFrag = defineFragment()({
+            id: true,
+            comments: { query: commentFrag, where: { approved: true } },
+        });
+        const raw = {
+            id: 'p1',
+            title: 'Hello',
+            comments: [
+                { id: 'c1', body: 'Great!', approved: true },
+                { id: 'c2', body: 'Nice', approved: false },
+            ],
+        };
+        const result = pickFields(raw, postFrag._fields);
+        expect(result).toEqual({
+            id: 'p1',
+            comments: [
+                { id: 'c1', body: 'Great!' },
+                { id: 'c2', body: 'Nice' },
+            ],
+        });
+        // title is not selected
+        expect(result).not.toHaveProperty('title');
+        // approved is not in commentFrag
+        expect(result.comments[0]).not.toHaveProperty('approved');
+    });
+    it('handles null relationship in RelationSelector', () => {
+        const userFrag = defineFragment()({ id: true, name: true });
+        const postFrag = defineFragment()({
+            id: true,
+            author: { query: userFrag, where: { role: 'admin' } },
+        });
+        const raw = { id: 'p1', author: null };
+        const result = pickFields(raw, postFrag._fields);
+        expect(result).toEqual({ id: 'p1', author: null });
+    });
+});
+// ─────────────────────────────────────────────────────────────
+// runQuery — RelationSelector with filter args
+// ─────────────────────────────────────────────────────────────
+describe('runQuery with RelationSelector', () => {
+    it('passes nested where/orderBy/take/skip to include entry', async () => {
+        const commentFrag = defineFragment()({ id: true, body: true });
+        const postFrag = defineFragment()({
+            id: true,
+            title: true,
+            comments: {
+                query: commentFrag,
+                where: { approved: true },
+                orderBy: { id: 'asc' },
+                take: 3,
+            },
+        });
+        const rawPosts = [
+            {
+                id: 'p1',
+                title: 'Hello',
+                comments: [{ id: 'c1', body: 'First!', approved: true }],
+            },
+        ];
+        const delegate = makeDelegate(rawPosts);
+        const ctx = makeContext({ postWithComments: delegate });
+        await runQuery(ctx, 'PostWithComments', postFrag);
+        expect(delegate.findMany).toHaveBeenCalledWith(expect.objectContaining({
+            include: {
+                comments: { where: { approved: true }, orderBy: { id: 'asc' }, take: 3 },
+            },
+        }));
+    });
+    it('picks only fragment fields from nested items in RelationSelector results', async () => {
+        const commentFrag = defineFragment()({ id: true, body: true });
+        const postFrag = defineFragment()({
+            id: true,
+            comments: { query: commentFrag, where: { approved: true } },
+        });
+        const rawPosts = [
+            {
+                id: 'p1',
+                title: 'Hello',
+                comments: [
+                    { id: 'c1', body: 'Yes!', approved: true },
+                    { id: 'c2', body: 'No', approved: false },
+                ],
+            },
+        ];
+        const ctx = makeContext({ postWithComments: makeDelegate(rawPosts) });
+        const results = await runQuery(ctx, 'PostWithComments', postFrag);
+        expect(results[0]).toEqual({
+            id: 'p1',
+            comments: [
+                { id: 'c1', body: 'Yes!' },
+                { id: 'c2', body: 'No' },
+            ],
+        });
+        expect(results[0]).not.toHaveProperty('title');
+    });
+});
+// ─────────────────────────────────────────────────────────────
+// Variables pattern — factory function
+// ─────────────────────────────────────────────────────────────
+describe('factory function (variables) pattern', () => {
+    it('creates different fragments with different runtime values', () => {
+        const commentFrag = defineFragment()({ id: true, body: true });
+        function makePostFrag(approvedOnly) {
+            return defineFragment()({
+                id: true,
+                comments: {
+                    query: commentFrag,
+                    where: { approved: approvedOnly },
+                },
+            });
+        }
+        const approvedFrag = makePostFrag(true);
+        const allFrag = makePostFrag(false);
+        const approvedInclude = buildInclude(approvedFrag._fields);
+        const allInclude = buildInclude(allFrag._fields);
+        expect(approvedInclude).toEqual({ comments: { where: { approved: true } } });
+        expect(allInclude).toEqual({ comments: { where: { approved: false } } });
+    });
+    it('ResultOf is the same shape regardless of runtime where values', () => {
+        const commentFrag = defineFragment()({ id: true, body: true });
+        const makePostFrag = (status) => defineFragment()({
+            id: true,
+            comments: { query: commentFrag, where: { approved: status } },
+        });
+        // Runtime usage (ensures the function is used, not just as a type)
+        const frag = makePostFrag(true);
+        expect(frag._type).toBe('fragment');
+        // Compile-time check: PostData should have id and comments
+        const r = { id: 'p1', comments: [{ id: 'c1', body: 'hi' }] };
+        expect(r.id).toBe('p1');
+        expect(r.comments).toHaveLength(1);
+    });
+});
+//# sourceMappingURL=index.test.js.map