@opensaas/stack-core 0.19.1 → 0.20.0

package/dist/query/index.d.ts

@@ -0,0 +1,299 @@
+/**
+ * Unwrap the item type from a field type, stripping null, undefined, and
+ * Array wrappers so we can constrain nested fragment shapes.
+ *
+ * Examples:
+ *   User | null     → User
+ *   User[]          → User
+ *   (User | null)[] → User
+ */
+type UnwrapItem<T> = NonNullable<T> extends Array<infer U> ? NonNullable<U> : NonNullable<T>;
+/**
+ * A selector for a relationship field.
+ *
+ * Two forms are accepted:
+ * 1. A `Fragment` directly (shorthand — no extra Prisma args on the nested query).
+ * 2. An object `{ query, where?, orderBy?, take?, skip? }` to combine a fragment
+ *    with Prisma filter/ordering/pagination applied to the nested relationship.
+ *
+ * @example Shorthand (most common)
+ * ```ts
+ * const postFrag = defineFragment<Post>()({
+ *   id: true,
+ *   author: authorFragment,   // shorthand
+ * } as const)
+ * ```
+ *
+ * @example With nested filtering
+ * ```ts
+ * const postFrag = defineFragment<Post>()({
+ *   id: true,
+ *   comments: {
+ *     query:   commentFragment,
+ *     where:   { approved: true },
+ *     orderBy: { createdAt: 'desc' },
+ *     take:    5,
+ *   },
+ * } as const)
+ * ```
+ *
+ * @example Variables via factory function
+ * ```ts
+ * function makePostFragment(status: string) {
+ *   return defineFragment<Post>()({
+ *     id:      true,
+ *     comments: { query: commentFragment, where: { status } },
+ *   } as const)
+ * }
+ * type PostData = ResultOf<ReturnType<typeof makePostFragment>>
+ * ```
+ */
+export type RelationSelector<TRelated extends Record<string, unknown>> = Fragment<TRelated, FieldSelection<TRelated>> | {
+    readonly query: Fragment<TRelated, FieldSelection<TRelated>>;
+    readonly where?: Record<string, unknown>;
+    readonly orderBy?: Record<string, 'asc' | 'desc'> | Array<Record<string, 'asc' | 'desc'>>;
+    readonly take?: number;
+    readonly skip?: number;
+};
+/**
+ * A field selection for model type `TItem`.
+ *
+ * Each key maps to:
+ * - `true`                — include the scalar/primitive field as-is
+ * - A `Fragment`          — include a relationship and recurse (shorthand)
+ * - A `RelationSelector`  — include a relationship with optional Prisma filter/ordering
+ *
+ * Only keys present in `TItem` are accepted. For relationship (object) fields
+ * you may pass a Fragment, a RelationSelector, or `true` (returns the raw Prisma
+ * value and loses type narrowing).
+ *
+ * @example
+ * ```ts
+ * const sel: FieldSelection<Post> = {
+ *   id: true,
+ *   title: true,
+ *   author: authorFragment,
+ *   comments: { query: commentFragment, where: { approved: true } },
+ * }
+ * ```
+ */
+export type FieldSelection<T> = {
+    readonly [K in keyof T]?: UnwrapItem<T[K]> extends Record<string, unknown> ? RelationSelector<UnwrapItem<T[K]>> | true : true;
+};
+/**
+ * A reusable, composable field-selection descriptor for model type `TItem`.
+ *
+ * Create with {@link defineFragment}. Compose by referencing another Fragment
+ * (or a {@link RelationSelector}) as the value for a relationship key.
+ *
+ * @example
+ * ```ts
+ * const userFragment = defineFragment<User>()({ id: true, name: true } as const)
+ * const postFragment = defineFragment<Post>()({
+ *   id: true,
+ *   title: true,
+ *   author: userFragment,
+ * } as const)
+ * ```
+ */
+export type Fragment<TItem, TFields extends FieldSelection<TItem> = FieldSelection<TItem>> = {
+    readonly _type: 'fragment';
+    readonly _fields: TFields;
+};
+/**
+ * @internal
+ * Extract the Fragment from either a Fragment directly or a RelationSelector object.
+ * Returns `never` for scalar `true` selections (so they fall to the scalar branch).
+ */
+type ExtractFragment<TSelector> = TSelector extends Fragment<infer TItem, infer TFields> ? Fragment<TItem, TFields> : TSelector extends {
+    readonly query: Fragment<infer TItem, infer TFields>;
+} ? Fragment<TItem, TFields> : never;
+/**
+ * @internal
+ * Map a FieldSelection over a model type, computing the picked output type.
+ */
+type SelectedFields<TItem, TFields extends FieldSelection<TItem>> = {
+    [K in keyof TFields & keyof TItem]: [ExtractFragment<TFields[K]>] extends [never] ? TItem[K] : TItem[K] extends Array<unknown> ? ResultOf<ExtractFragment<TFields[K]>>[] : null extends TItem[K] ? ResultOf<ExtractFragment<TFields[K]>> | null : undefined extends TItem[K] ? ResultOf<ExtractFragment<TFields[K]>> | undefined : ResultOf<ExtractFragment<TFields[K]>>;
+};
+/**
+ * Infer the TypeScript result type from a Fragment.
+ *
+ * Analogous to `gql.tada`'s `ResultOf` helper — given a fragment definition,
+ * `ResultOf` tells you exactly what shape you will receive at runtime.
+ *
+ * - Scalar fields selected with `true` retain their original Prisma type.
+ * - Relationship fields selected with a nested Fragment/RelationSelector are
+ *   recursively narrowed.
+ * - Nullability and array wrappers from the original model type are preserved.
+ *
+ * @example
+ * ```ts
+ * type UserData  = ResultOf<typeof userFragment>
+ * // → { id: string; name: string }
+ *
+ * type PostData  = ResultOf<typeof postFragment>
+ * // → { id: string; title: string; author: { id: string; name: string } | null }
+ * ```
+ */
+export type ResultOf<F> = F extends Fragment<infer TItem, infer TFields> ? SelectedFields<TItem, TFields> : never;
+/**
+ * Arguments accepted by {@link runQuery}.
+ */
+export type QueryArgs = {
+    /** Prisma where filter. The access control layer will additionally scope results. */
+    where?: Record<string, unknown>;
+    /** Prisma orderBy clause. Pass a single object or an array for multi-column ordering. */
+    orderBy?: Record<string, 'asc' | 'desc'> | Array<Record<string, 'asc' | 'desc'>>;
+    /** Maximum number of records to return. */
+    take?: number;
+    /** Number of records to skip (for pagination). */
+    skip?: number;
+};
+/**
+ * Minimal context shape required by the query runners.
+ * Compatible with the full `AccessContext` produced by `getContext()`.
+ */
+export interface QueryRunnerContext {
+    db: {
+        [key: string]: {
+            findMany: (args?: unknown) => Promise<unknown[]>;
+            findFirst: (args?: unknown) => Promise<unknown>;
+        };
+    };
+}
+/**
+ * Create a type-safe, reusable fragment for a given model type.
+ *
+ * The function is curried so that TypeScript can infer both the model type
+ * (from the explicit type parameter) and the field selection (from the
+ * argument), without requiring you to repeat yourself.
+ *
+ * @example Basic usage
+ * ```ts
+ * import type { User } from '.prisma/client'
+ * import { defineFragment } from '@opensaas/stack-core'
+ *
+ * export const userFragment = defineFragment<User>()({
+ *   id:    true,
+ *   name:  true,
+ *   email: true,
+ * } as const)
+ * ```
+ *
+ * @example Compose fragments
+ * ```ts
+ * import type { Post } from '.prisma/client'
+ *
+ * export const postFragment = defineFragment<Post>()({
+ *   id:      true,
+ *   title:   true,
+ *   author:  userFragment,
+ * } as const)
+ * ```
+ *
+ * @example Nested filtering with RelationSelector
+ * ```ts
+ * export const postWithApprovedComments = defineFragment<Post>()({
+ *   id:    true,
+ *   title: true,
+ *   comments: {
+ *     query:   commentFragment,
+ *     where:   { approved: true },
+ *     orderBy: { createdAt: 'desc' },
+ *     take:    5,
+ *   },
+ * } as const)
+ * ```
+ *
+ * @example Variables via factory function
+ * ```ts
+ * function makePostFragment(status: string) {
+ *   return defineFragment<Post>()({
+ *     id:      true,
+ *     comments: { query: commentFragment, where: { status } },
+ *   } as const)
+ * }
+ * type PostData = ResultOf<ReturnType<typeof makePostFragment>>
+ *
+ * const posts = await context.db.post.findMany({
+ *   query: makePostFragment('approved'),
+ *   where: { published: true },
+ * })
+ * ```
+ */
+export declare function defineFragment<TItem>(): <TFields extends FieldSelection<TItem>>(fields: TFields) => Fragment<TItem, TFields>;
+/** @internal */
+export declare function isFragment(value: unknown): value is Fragment<unknown, FieldSelection<unknown>>;
+/**
+ * Walk a field selection and build the Prisma `include` map needed to eagerly
+ * load all nested relationship fragments/selectors.
+ *
+ * Scalar fields (`true`) do not require an include entry — Prisma returns all
+ * scalar columns by default. Only relationship fields backed by a Fragment or
+ * RelationSelector generate include entries (recursively).
+ *
+ * Exported for use in `context/index.ts` when the `query` parameter is present.
+ * @internal
+ */
+export declare function buildInclude(fields: FieldSelection<unknown>): Record<string, unknown> | undefined;
+/**
+ * Recursively pick only the fields requested by a fragment from a raw Prisma
+ * result object. This ensures the runtime shape exactly matches the type
+ * produced by `ResultOf<F>`.
+ *
+ * Exported for use in `context/index.ts`.
+ * @internal
+ */
+export declare function pickFields<TItem, TFields extends FieldSelection<TItem>>(item: TItem, fields: TFields): SelectedFields<TItem, TFields>;
+/**
+ * Execute a fragment-based query against a list, returning all matching
+ * records shaped to the fragment's field selection.
+ *
+ * Under the hood this calls `context.db[listKey].findMany()`, so all access
+ * control rules defined in your config are still enforced.
+ *
+ * **Tip:** You can also call `context.db.post.findMany({ query: fragment, ... })`
+ * directly — both forms produce the same result.
+ *
+ * @param context - An `AccessContext` (or any object with a compatible `db`).
+ * @param listKey - The PascalCase list name (e.g. `'Post'`, `'BlogPost'`).
+ * @param fragment - A fragment created with {@link defineFragment}.
+ * @param args     - Optional query arguments (where, orderBy, take, skip).
+ * @returns        An array typed to exactly the fragment's field selection.
+ *
+ * @example
+ * ```ts
+ * const posts = await runQuery(context, 'Post', postFragment, {
+ *   where:   { published: true },
+ *   orderBy: { createdAt: 'desc' },
+ *   take:    10,
+ * })
+ * // posts: Array<ResultOf<typeof postFragment>>
+ * ```
+ */
+export declare function runQuery<TItem, TFields extends FieldSelection<TItem>>(context: QueryRunnerContext, listKey: string, fragment: Fragment<TItem, TFields>, args?: QueryArgs): Promise<SelectedFields<TItem, TFields>[]>;
+/**
+ * Execute a fragment-based query that returns a single record (or `null`).
+ *
+ * Under the hood this calls `context.db[listKey].findFirst()`, so all access
+ * control rules are still enforced.
+ *
+ * **Tip:** You can also call `context.db.post.findUnique({ where: { id }, query: fragment })`
+ * directly.
+ *
+ * @param context - An `AccessContext` (or any object with a compatible `db`).
+ * @param listKey - The PascalCase list name (e.g. `'Post'`).
+ * @param fragment - A fragment created with {@link defineFragment}.
+ * @param where    - A Prisma where clause to identify the record.
+ * @returns        The matched record shaped to the fragment, or `null`.
+ *
+ * @example
+ * ```ts
+ * const post = await runQueryOne(context, 'Post', postFragment, { id: postId })
+ * if (!post) return notFound()
+ * // post: ResultOf<typeof postFragment>
+ * ```
+ */
+export declare function runQueryOne<TItem, TFields extends FieldSelection<TItem>>(context: QueryRunnerContext, listKey: string, fragment: Fragment<TItem, TFields>, where: Record<string, unknown>): Promise<SelectedFields<TItem, TFields> | null>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/query/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/query/index.ts"],"names":[],"mappings":"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"}

package/dist/query/index.js

@@ -0,0 +1,255 @@
+import { getDbKey } from '../lib/case-utils.js';
+// ─────────────────────────────────────────────────────────────
+// Fragment factory
+// ─────────────────────────────────────────────────────────────
+/**
+ * Create a type-safe, reusable fragment for a given model type.
+ *
+ * The function is curried so that TypeScript can infer both the model type
+ * (from the explicit type parameter) and the field selection (from the
+ * argument), without requiring you to repeat yourself.
+ *
+ * @example Basic usage
+ * ```ts
+ * import type { User } from '.prisma/client'
+ * import { defineFragment } from '@opensaas/stack-core'
+ *
+ * export const userFragment = defineFragment<User>()({
+ *   id:    true,
+ *   name:  true,
+ *   email: true,
+ * } as const)
+ * ```
+ *
+ * @example Compose fragments
+ * ```ts
+ * import type { Post } from '.prisma/client'
+ *
+ * export const postFragment = defineFragment<Post>()({
+ *   id:      true,
+ *   title:   true,
+ *   author:  userFragment,
+ * } as const)
+ * ```
+ *
+ * @example Nested filtering with RelationSelector
+ * ```ts
+ * export const postWithApprovedComments = defineFragment<Post>()({
+ *   id:    true,
+ *   title: true,
+ *   comments: {
+ *     query:   commentFragment,
+ *     where:   { approved: true },
+ *     orderBy: { createdAt: 'desc' },
+ *     take:    5,
+ *   },
+ * } as const)
+ * ```
+ *
+ * @example Variables via factory function
+ * ```ts
+ * function makePostFragment(status: string) {
+ *   return defineFragment<Post>()({
+ *     id:      true,
+ *     comments: { query: commentFragment, where: { status } },
+ *   } as const)
+ * }
+ * type PostData = ResultOf<ReturnType<typeof makePostFragment>>
+ *
+ * const posts = await context.db.post.findMany({
+ *   query: makePostFragment('approved'),
+ *   where: { published: true },
+ * })
+ * ```
+ */
+export function defineFragment() {
+    return function (fields) {
+        return { _type: 'fragment', _fields: fields };
+    };
+}
+// ─────────────────────────────────────────────────────────────
+// Runtime helpers — exported for use in context/index.ts
+// ─────────────────────────────────────────────────────────────
+/** @internal */
+export function isFragment(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        '_type' in value &&
+        value._type === 'fragment');
+}
+/**
+ * Walk a field selection and build the Prisma `include` map needed to eagerly
+ * load all nested relationship fragments/selectors.
+ *
+ * Scalar fields (`true`) do not require an include entry — Prisma returns all
+ * scalar columns by default. Only relationship fields backed by a Fragment or
+ * RelationSelector generate include entries (recursively).
+ *
+ * Exported for use in `context/index.ts` when the `query` parameter is present.
+ * @internal
+ */
+export function buildInclude(fields) {
+    const include = {};
+    let hasIncludes = false;
+    for (const [key, value] of Object.entries(fields)) {
+        if (value === null || value === true || typeof value !== 'object')
+            continue;
+        const val = value;
+        // ── Shorthand: Fragment directly ──────────────────────────
+        if (isFragment(val)) {
+            hasIncludes = true;
+            const nestedInclude = buildInclude(val._fields);
+            include[key] = nestedInclude ? { include: nestedInclude } : true;
+            continue;
+        }
+        // ── RelationSelector: { query, where?, orderBy?, take?, skip? } ──
+        if ('query' in val && isFragment(val.query)) {
+            hasIncludes = true;
+            const selector = val;
+            const nestedInclude = buildInclude(selector.query._fields);
+            const includeEntry = {};
+            if (selector.where !== undefined)
+                includeEntry.where = selector.where;
+            if (selector.orderBy !== undefined)
+                includeEntry.orderBy = selector.orderBy;
+            if (selector.take !== undefined)
+                includeEntry.take = selector.take;
+            if (selector.skip !== undefined)
+                includeEntry.skip = selector.skip;
+            if (nestedInclude)
+                includeEntry.include = nestedInclude;
+            include[key] = Object.keys(includeEntry).length > 0 ? includeEntry : true;
+            continue;
+        }
+    }
+    return hasIncludes ? include : undefined;
+}
+/**
+ * Recursively pick only the fields requested by a fragment from a raw Prisma
+ * result object. This ensures the runtime shape exactly matches the type
+ * produced by `ResultOf<F>`.
+ *
+ * Exported for use in `context/index.ts`.
+ * @internal
+ */
+export function pickFields(item, fields) {
+    const result = {};
+    for (const [key, value] of Object.entries(fields)) {
+        const fieldValue = item[key];
+        if (value === true) {
+            result[key] = fieldValue;
+            continue;
+        }
+        if (value === null || typeof value !== 'object')
+            continue;
+        const val = value;
+        // ── Shorthand: Fragment directly ──────────────────────────
+        if (isFragment(val)) {
+            if (Array.isArray(fieldValue)) {
+                result[key] = fieldValue.map((elem) => pickFields(elem, val._fields));
+            }
+            else if (fieldValue === null || fieldValue === undefined) {
+                result[key] = fieldValue;
+            }
+            else {
+                result[key] = pickFields(fieldValue, val._fields);
+            }
+            continue;
+        }
+        // ── RelationSelector: { query, where?, ... } ──────────────
+        if ('query' in val && isFragment(val.query)) {
+            const nestedFrag = val.query;
+            if (Array.isArray(fieldValue)) {
+                result[key] = fieldValue.map((elem) => pickFields(elem, nestedFrag._fields));
+            }
+            else if (fieldValue === null || fieldValue === undefined) {
+                result[key] = fieldValue;
+            }
+            else {
+                result[key] = pickFields(fieldValue, nestedFrag._fields);
+            }
+            continue;
+        }
+    }
+    return result;
+}
+// ─────────────────────────────────────────────────────────────
+// Standalone query runners
+// ─────────────────────────────────────────────────────────────
+/**
+ * Execute a fragment-based query against a list, returning all matching
+ * records shaped to the fragment's field selection.
+ *
+ * Under the hood this calls `context.db[listKey].findMany()`, so all access
+ * control rules defined in your config are still enforced.
+ *
+ * **Tip:** You can also call `context.db.post.findMany({ query: fragment, ... })`
+ * directly — both forms produce the same result.
+ *
+ * @param context - An `AccessContext` (or any object with a compatible `db`).
+ * @param listKey - The PascalCase list name (e.g. `'Post'`, `'BlogPost'`).
+ * @param fragment - A fragment created with {@link defineFragment}.
+ * @param args     - Optional query arguments (where, orderBy, take, skip).
+ * @returns        An array typed to exactly the fragment's field selection.
+ *
+ * @example
+ * ```ts
+ * const posts = await runQuery(context, 'Post', postFragment, {
+ *   where:   { published: true },
+ *   orderBy: { createdAt: 'desc' },
+ *   take:    10,
+ * })
+ * // posts: Array<ResultOf<typeof postFragment>>
+ * ```
+ */
+export async function runQuery(context, listKey, fragment, args) {
+    const dbKey = getDbKey(listKey);
+    const include = buildInclude(fragment._fields);
+    const findManyArgs = {};
+    if (args?.where !== undefined)
+        findManyArgs.where = args.where;
+    if (args?.orderBy !== undefined)
+        findManyArgs.orderBy = args.orderBy;
+    if (args?.take !== undefined)
+        findManyArgs.take = args.take;
+    if (args?.skip !== undefined)
+        findManyArgs.skip = args.skip;
+    if (include)
+        findManyArgs.include = include;
+    const results = await context.db[dbKey].findMany(Object.keys(findManyArgs).length > 0 ? findManyArgs : undefined);
+    return results.map((item) => pickFields(item, fragment._fields));
+}
+/**
+ * Execute a fragment-based query that returns a single record (or `null`).
+ *
+ * Under the hood this calls `context.db[listKey].findFirst()`, so all access
+ * control rules are still enforced.
+ *
+ * **Tip:** You can also call `context.db.post.findUnique({ where: { id }, query: fragment })`
+ * directly.
+ *
+ * @param context - An `AccessContext` (or any object with a compatible `db`).
+ * @param listKey - The PascalCase list name (e.g. `'Post'`).
+ * @param fragment - A fragment created with {@link defineFragment}.
+ * @param where    - A Prisma where clause to identify the record.
+ * @returns        The matched record shaped to the fragment, or `null`.
+ *
+ * @example
+ * ```ts
+ * const post = await runQueryOne(context, 'Post', postFragment, { id: postId })
+ * if (!post) return notFound()
+ * // post: ResultOf<typeof postFragment>
+ * ```
+ */
+export async function runQueryOne(context, listKey, fragment, where) {
+    const dbKey = getDbKey(listKey);
+    const include = buildInclude(fragment._fields);
+    const findFirstArgs = { where };
+    if (include)
+        findFirstArgs.include = include;
+    const item = await context.db[dbKey].findFirst(findFirstArgs);
+    if (item === null || item === undefined)
+        return null;
+    return pickFields(item, fragment._fields);
+}
+//# sourceMappingURL=index.js.map

package/dist/query/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/query/index.ts"],"names":[],"mappings":"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"}

package/dist/query/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

package/dist/query/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../../src/query/index.test.ts"],"names":[],"mappings":""}