naystack 1.5.9 → 1.5.11

package/dist/graphql/server.d.ts

@@ -2,12 +2,67 @@ import { OperationVariables } from '@apollo/client';
 import { TypedDocumentNode } from '@graphql-typed-document-node/core';
 import React__default, { FC } from 'react';
 
+/** Component props type minus loading and data (inferred from Injector Component). */
 type OmittedProps<Y> = Omit<Omit<Y, "loading">, "data">;
+/** Props for Injector: either optional or required based on remaining Component props. */
 type ComponentProps<Y> = OmittedProps<Y> extends Record<string, never> ? {
     props?: object;
 } : {
     props: OmittedProps<Y>;
 };
+/**
+ * Server component that wraps a client component with server-fetched data using Suspense.
+ *
+ * While the `fetch` function is resolving, the `Component` is rendered with `loading={true}` (and no `data`).
+ * Once the fetch resolves, the `Component` re-renders with `loading={false}` and `data` set to the result.
+ *
+ * This is the primary way to inject server-side data into client components in naystack.
+ * Use `.authCall()` or `.call()` from your query definitions inside the `fetch` function.
+ *
+ * @param injectorProps - Configuration object.
+ * @param injectorProps.fetch - Async function that returns the data to pass to the component. Runs on the server.
+ * @param injectorProps.Component - React component that receives `{ data?: T; loading: boolean }` plus any extra props.
+ * @param injectorProps.props - Optional. Any additional props to pass to `Component`. Required if the Component has props other than `data` and `loading`.
+ * @returns A React element that suspends until `fetch()` completes, then renders `Component` with the data.
+ *
+ * @example Simple usage:
+ * ```tsx
+ * import { Injector } from "naystack/graphql/server";
+ * import getCurrentUser from "@/app/api/(graphql)/User/resolvers/get-current-user";
+ * import AuthChecker from "./components/auth-checker";
+ *
+ * export default async function Layout({ children }: { children: React.ReactNode }) {
+ *   return (
+ *     <div>
+ *       {children}
+ *       <Injector fetch={getCurrentUser.authCall} Component={AuthChecker} />
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Fetching multiple queries:
+ * ```tsx
+ * import { Injector } from "naystack/graphql/server";
+ * import getCurrentUser from "@/app/api/(graphql)/User/resolvers/get-current-user";
+ * import getChats from "@/app/api/(graphql)/Chat/resolvers/get-chats";
+ * import { ChatWindow } from "./components/chat-window";
+ *
+ * export default async function ChatPage() {
+ *   return (
+ *     <Injector
+ *       fetch={async () => ({
+ *         user: await getCurrentUser.authCall(),
+ *         chats: await getChats.authCall(),
+ *       })}
+ *       Component={ChatWindow}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @category GraphQL
+ */
 declare function Injector<T, Y>({ fetch, Component, props, }: {
     fetch: () => Promise<T>;
     Component: FC<{
@@ -15,6 +70,39 @@ declare function Injector<T, Y>({ fetch, Component, props, }: {
         loading: boolean;
     } & Y>;
 } & ComponentProps<Y>): React__default.JSX.Element;
+/**
+ * Runs a raw GraphQL query on the server using the registered Apollo client.
+ * Cookies are forwarded automatically so the backend can identify the user.
+ *
+ * Use this in Server Components, Server Actions, or route handlers when you need to
+ * run a query against the GraphQL endpoint (rather than calling a resolver directly with `.call()`/`.authCall()`).
+ *
+ * Supports Next.js ISR via `revalidate` and on-demand revalidation via `tags`.
+ *
+ * @param _query - A `TypedDocumentNode` (e.g. from codegen) defining the query and its result type.
+ * @param options - Optional query options.
+ * @param options.variables - Variables object for the query (must match the document's variable types).
+ * @param options.revalidate - Next.js revalidate in seconds; when set, enables caching with this TTL.
+ * @param options.tags - Next.js cache tags for on-demand revalidation.
+ * @param options.noCookie - If `true`, the request is sent without cookies (unauthenticated).
+ * @returns Promise resolving to the query result data (typed by the document).
+ *
+ * @example
+ * ```ts
+ * import { query } from "naystack/graphql/server";
+ * import { GetUserDocument } from "@/generated/graphql";
+ *
+ * // In a Server Component:
+ * const data = await query(GetUserDocument, {
+ *   variables: { id: userId },
+ *   revalidate: 60,       // Cache for 60s (Next.js ISR)
+ *   tags: ["user"],        // For on-demand revalidation
+ * });
+ * return <Profile user={data.user} />;
+ * ```
+ *
+ * @category GraphQL
+ */
 declare const query: <T, V extends OperationVariables>(_query: TypedDocumentNode<T, V>, options?: {
     variables?: V;
     revalidate?: number;

package/dist/graphql/types.d.mts

@@ -1,7 +1,28 @@
+/**
+ * Request context passed to GraphQL resolvers. Built automatically from the request's
+ * `Authorization` header or refresh cookie by the built-in `getContext`.
+ *
+ * @property userId - Authenticated user id, or `null` if the request is unauthenticated.
+ * @property isRefreshID - `true` if the user was identified via the refresh cookie (not an access token).
+ *   When `isRefreshID` is true, mutations are blocked by default (only queries are allowed via refresh cookie).
+ *
+ * @category GraphQL
+ */
 interface Context {
     userId: number | null;
     isRefreshID?: boolean;
 }
+/**
+ * Context for resolvers that require authentication (`authorized: true`). The `userId` is guaranteed to be non-null.
+ *
+ * When you set `authorized: true` on a `query()` or `field()`, the resolver's `ctx` parameter is typed as `AuthorizedContext`
+ * instead of `Context`, so you can safely access `ctx.userId` without null checks.
+ *
+ * @property userId - Authenticated user id (guaranteed non-null).
+ * @property isRefreshID - `true` if identified via refresh cookie.
+ *
+ * @category GraphQL
+ */
 interface AuthorizedContext {
     userId: number;
     isRefreshID?: boolean;

package/dist/graphql/types.d.ts

@@ -1,7 +1,28 @@
+/**
+ * Request context passed to GraphQL resolvers. Built automatically from the request's
+ * `Authorization` header or refresh cookie by the built-in `getContext`.
+ *
+ * @property userId - Authenticated user id, or `null` if the request is unauthenticated.
+ * @property isRefreshID - `true` if the user was identified via the refresh cookie (not an access token).
+ *   When `isRefreshID` is true, mutations are blocked by default (only queries are allowed via refresh cookie).
+ *
+ * @category GraphQL
+ */
 interface Context {
     userId: number | null;
     isRefreshID?: boolean;
 }
+/**
+ * Context for resolvers that require authentication (`authorized: true`). The `userId` is guaranteed to be non-null.
+ *
+ * When you set `authorized: true` on a `query()` or `field()`, the resolver's `ctx` parameter is typed as `AuthorizedContext`
+ * instead of `Context`, so you can safely access `ctx.userId` without null checks.
+ *
+ * @property userId - Authenticated user id (guaranteed non-null).
+ * @property isRefreshID - `true` if identified via refresh cookie.
+ *
+ * @category GraphQL
+ */
 interface AuthorizedContext {
     userId: number;
     isRefreshID?: boolean;

package/dist/graphql/utils.d.mts

@@ -2,20 +2,29 @@ import { GraphQLScalarType } from 'graphql';
 import { ClassType, Query, Arg } from 'type-graphql';
 import { AuthorizedContext, Context } from './types.mjs';
 
+/** Options for @Query() / @Mutation() return type (e.g. nullable). */
 type ReturnOptions = Parameters<typeof Query>[1];
+/** Options for @Arg() (e.g. nullable). */
 type ArgsOptions = Parameters<typeof Arg>[2];
+/** Maps nullable keys to optional and normalizes null/undefined. */
 type NormalizeNullUndefined<T> = {
     [K in keyof T as null extends T[K] ? K : never]?: Exclude<T[K], undefined>;
 } & {
     [K in keyof T as null extends T[K] ? never : K]: undefined extends T[K] ? Exclude<T[K], undefined> | null : T[K];
 };
+/** Adds nullable option to Query/Arg options. */
 type NullableOptions<T, X extends boolean> = T & {
     nullable: X;
 };
+/** Resolves a GraphQL type (class, scalar, primitive) to TS type. */
 type ParsedGQLType<T, MergeNullUndefined extends boolean> = T extends StringConstructor ? string : T extends NumberConstructor ? number : T extends BooleanConstructor ? boolean : T extends GraphQLScalarType<infer U> ? U : T extends ClassType<infer U> ? MergeNullUndefined extends true ? NormalizeNullUndefined<U> : U : T extends Record<infer K, string | number> ? T[K] : void;
+/** Array-aware ParsedGQLType. */
 type ParsedGQLTypeWithArray<T, MergeNullUndefined extends boolean> = T extends Array<infer U> ? ParsedGQLType<U, MergeNullUndefined>[] : ParsedGQLType<T, MergeNullUndefined>;
+/** Adds null/undefined when nullable. */
 type ParsedGQLTypeWithNullability<T, IsNullable extends boolean, MergeNullUndefined extends boolean> = IsNullable extends true ? ParsedGQLTypeWithArray<T, MergeNullUndefined> | null | undefined : ParsedGQLTypeWithArray<T, MergeNullUndefined>;
+/** Allows resolver to return T or Promise<T>. */
 type Promisify<T> = T | Promise<T>;
+/** Base for query/field definition (output, input, options). */
 interface BaseDefinition<T, U, IsAuth extends boolean = false, OutputNullable extends boolean = false, InputNullable extends boolean = false> {
     output: T;
     outputOptions?: NullableOptions<ReturnOptions, OutputNullable>;
@@ -23,26 +32,234 @@ interface BaseDefinition<T, U, IsAuth extends boolean = false, OutputNullable ex
     inputOptions?: NullableOptions<ArgsOptions, InputNullable>;
     authorized?: IsAuth;
 }
+/**
+ * Full query/mutation definition returned by {@link query}. Contains the resolver function,
+ * plus `.call()` and `.authCall()` for direct server-side invocation.
+ *
+ * @category GraphQL
+ */
 interface QueryDefinition<T, U, IsAuth extends boolean = false, OutputNullable extends boolean = false, InputNullable extends boolean = false, R extends Promisify<ParsedGQLTypeWithNullability<T, OutputNullable, true>> = Promisify<ParsedGQLTypeWithNullability<T, OutputNullable, true>>> extends BaseDefinition<T, U, IsAuth, OutputNullable, InputNullable> {
     fn: (ctx: IsAuth extends true ? AuthorizedContext : Context, data: ParsedGQLTypeWithNullability<U, InputNullable, false>) => R;
+    /** Calls the resolver server-side. For authorized queries, reads the refresh cookie; for non-authorized, passes null userId. */
     call: (data: ParsedGQLTypeWithNullability<U, InputNullable, false>) => Promise<Awaited<R>>;
+    /** Calls the resolver server-side with authentication (always reads the refresh cookie). Use in Server Components. */
     authCall: (data: ParsedGQLTypeWithNullability<U, InputNullable, false>) => Promise<Awaited<R>>;
     mutation?: boolean;
 }
+/**
+ * Defines a type-graphql query or mutation with typed input/output and optional auth.
+ * Use with {@link QueryLibrary} to build resolver classes for `initGraphQLServer`.
+ *
+ * Each query definition gets `.call(data)` and `.authCall(data)` methods for direct server-side invocation
+ * (e.g. in Server Components or other resolvers). Both are cached via React's `cache()`.
+ *
+ * @param fn - Resolver function: `(ctx, data) => result`.
+ *   - `ctx` is `Context` (or `AuthorizedContext` when `authorized: true`) with `userId`.
+ *   - `data` is the typed GraphQL input (or `void` if no input).
+ * @param options - Configuration for the query/mutation.
+ * @param options.output - The GraphQL return type (type-graphql `@ObjectType` class, `String`, `Boolean`, `Number`, etc.).
+ * @param options.input - Optional GraphQL input type (`@InputType` class or scalar) for the `input` argument.
+ * @param options.outputOptions - Optional. Set `{ nullable: true }` to allow null returns.
+ * @param options.inputOptions - Optional. Set `{ nullable: true }` to allow null input.
+ * @param options.authorized - If `true`, the resolver requires an authenticated user. `ctx` is typed as `AuthorizedContext` (non-null `userId`).
+ * @param options.mutation - If `true`, registers as a `@Mutation`; otherwise registers as a `@Query`.
+ * @returns A `QueryDefinition` with `.call(data)` and `.authCall(data)` for server-side invocation.
+ *
+ * @example Simple query (no input, nullable output):
+ * ```ts
+ * import { query } from "naystack/graphql";
+ *
+ * export default query(
+ *   async (ctx) => {
+ *     if (!ctx.userId) return null;
+ *     const [user] = await db.select().from(UserTable).where(eq(UserTable.id, ctx.userId));
+ *     return user || null;
+ *   },
+ *   { output: User, outputOptions: { nullable: true } },
+ * );
+ * ```
+ *
+ * @example Mutation with input and authorization:
+ * ```ts
+ * export default query(
+ *   async (ctx, input: SubmitFeedbackInput) => {
+ *     await db.insert(FeedbackTable).values({ userId: ctx.userId, score: input.score, text: input.text });
+ *     return true;
+ *   },
+ *   { output: Boolean, input: SubmitFeedbackInput, authorized: true, mutation: true },
+ * );
+ * ```
+ *
+ * @example Server-side invocation in a Server Component:
+ * ```ts
+ * const user = await getCurrentUser.authCall();   // Reads refresh cookie for auth
+ * const planets = await getPlanets.call();         // No auth needed
+ * ```
+ *
+ * @category GraphQL
+ */
 declare function query<T, U, IsAuth extends boolean = false, OutputNullable extends boolean = false, InputNullable extends boolean = false, R extends Promisify<ParsedGQLTypeWithNullability<T, OutputNullable, true>> = Promisify<ParsedGQLTypeWithNullability<T, OutputNullable, true>>>(fn: (ctx: IsAuth extends true ? AuthorizedContext : Context, data: ParsedGQLTypeWithNullability<U, InputNullable, false>) => R, options: Omit<QueryDefinition<T, U, IsAuth, OutputNullable, InputNullable, R>, "fn" | "authCall" | "call">): QueryDefinition<T, U, IsAuth, OutputNullable, InputNullable, R>;
+/**
+ * Full field resolver definition returned by {@link field}. Contains the resolver function,
+ * plus `.call()` and `.authCall()` for direct server-side invocation.
+ *
+ * @category GraphQL
+ */
 interface FieldResolverDefinition<T, U, Root, IsAuth extends boolean = false, OutputNullable extends boolean = false, InputNullable extends boolean = false, R extends Promisify<ParsedGQLTypeWithNullability<T, OutputNullable, true>> = Promisify<ParsedGQLTypeWithNullability<T, OutputNullable, true>>> extends BaseDefinition<T, U, IsAuth, OutputNullable, InputNullable> {
     fn: (root: Root, ctx: IsAuth extends true ? AuthorizedContext : Context, data: ParsedGQLTypeWithNullability<U, InputNullable, false>) => R;
+    /** Calls the field resolver server-side. For authorized fields, reads the refresh cookie. */
     call: (root: Root, data: ParsedGQLTypeWithNullability<U, InputNullable, false>) => Promise<Awaited<R>>;
+    /** Calls the field resolver server-side with authentication (always reads the refresh cookie). */
     authCall: (root: Root, data: ParsedGQLTypeWithNullability<U, InputNullable, false>) => Promise<Awaited<R>>;
 }
+/**
+ * Defines a type-graphql field resolver with typed root, context, and input.
+ * Use with {@link FieldLibrary} to attach computed fields to a parent GraphQL type.
+ *
+ * Like `query()`, each field definition gets `.call(root, data)` and `.authCall(root, data)` for server-side invocation.
+ *
+ * @param fn - Resolver function: `(root, ctx, data) => result`.
+ *   - `root` is the parent object (e.g. the `User` row from the database).
+ *   - `ctx` is `Context` (or `AuthorizedContext` when `authorized: true`).
+ *   - `data` is the optional typed input argument.
+ * @param options - Configuration (same as `query()` but without `mutation`).
+ * @returns A `FieldResolverDefinition` with `.call` and `.authCall` for server-side invocation.
+ *
+ * @example
+ * ```ts
+ * import { field } from "naystack/graphql";
+ *
+ * // Resolve the "seller" field on a Property type
+ * const seller = field(
+ *   async (property: PropertyDB) => {
+ *     if (!property.sellerId) return null;
+ *     const [seller] = await db.select().from(ContactTable).where(eq(ContactTable.id, property.sellerId));
+ *     return seller || null;
+ *   },
+ *   { output: ContactGQL, outputOptions: { nullable: true } },
+ * );
+ * ```
+ *
+ * @example Inline in a FieldLibrary:
+ * ```ts
+ * const OrgFields = FieldLibrary<OrgDB>(OrgGQL, {
+ *   access: field(
+ *     async (root, ctx) => {
+ *       if (!ctx.userId) return null;
+ *       return checkOrgAccess(ctx.userId, root.id);
+ *     },
+ *     { output: AccessRole, outputOptions: { nullable: true } },
+ *   ),
+ * });
+ * ```
+ *
+ * @category GraphQL
+ */
 declare function field<T, U, IsAuth extends boolean, Root, OutputNullable extends boolean = false, InputNullable extends boolean = false, R extends Promisify<ParsedGQLTypeWithNullability<T, OutputNullable, true>> = Promisify<ParsedGQLTypeWithNullability<T, OutputNullable, true>>>(fn: (root: Root, ctx: IsAuth extends true ? AuthorizedContext : Context, data: ParsedGQLTypeWithNullability<U, InputNullable, false>) => R, options: Omit<FieldResolverDefinition<T, U, Root, IsAuth, OutputNullable, InputNullable, R>, "fn" | "authCall" | "call">): FieldResolverDefinition<T, U, Root, IsAuth, OutputNullable, InputNullable, R>;
+/**
+ * Builds a type-graphql `@Resolver` class from a map of query/mutation definitions created with {@link query}.
+ * Each key in the `queries` object becomes a Query or Mutation field on the GraphQL schema.
+ *
+ * Pass the returned class in the `resolvers` array of `initGraphQLServer`.
+ *
+ * @param queries - Object mapping GraphQL field names to `QueryDefinition`s (from `query()`).
+ *   Each key becomes the field name in the schema. Mutations are determined by `{ mutation: true }` in the definition.
+ * @returns A `@Resolver` class suitable for `initGraphQLServer`.
+ *
+ * @example
+ * ```ts
+ * import { QueryLibrary, query } from "naystack/graphql";
+ * import getCurrentUser from "./resolvers/get-current-user";
+ * import updateUser from "./resolvers/update-user";
+ * import onboardUser from "./resolvers/onboard-user";
+ *
+ * export const UserResolvers = QueryLibrary({
+ *   getCurrentUser,  // becomes Query.getCurrentUser
+ *   updateUser,      // becomes Mutation.updateUser (if mutation: true)
+ *   onboardUser,     // becomes Mutation.onboardUser (if mutation: true)
+ * });
+ * ```
+ *
+ * @category GraphQL
+ */
 declare function QueryLibrary<T extends Record<string, QueryDefinition<any, any, any, any, any, any>>>(queries: T): {
     new (): {};
 };
+/**
+ * Builds a type-graphql `@Resolver(() => type)` class that resolves computed fields on a parent GraphQL type.
+ * Each key in the `queries` object becomes a `@FieldResolver` on that type.
+ *
+ * Pass the returned class in the `resolvers` array of `initGraphQLServer`.
+ *
+ * @typeParam X - The database/plain type of the parent object (e.g. `UserDB`).
+ * @param type - The parent GraphQL type class (e.g. `User`). Must be a `@ObjectType` class.
+ * @param queries - Object mapping field names to `FieldResolverDefinition`s (from `field()`).
+ * @returns A `@Resolver` class for the given type; pass it in `initGraphQLServer`'s resolvers array.
+ *
+ * @example
+ * ```ts
+ * import { FieldLibrary, field } from "naystack/graphql";
+ * import { User } from "./types";
+ * import type { UserDB } from "./db";
+ * import organizations from "./resolvers/organizations-field";
+ *
+ * export const UserFieldResolvers = FieldLibrary<UserDB>(User, {
+ *   organizations,   // Resolves User.organizations from the UserDB row
+ * });
+ * ```
+ *
+ * @example With inline field definitions:
+ * ```ts
+ * export const OrgFieldResolvers = FieldLibrary<OrgDB>(OrgGQL, {
+ *   access: field(
+ *     async (root, ctx) => checkOrgAccess(ctx.userId, root.id),
+ *     { output: AccessRole, outputOptions: { nullable: true } },
+ *   ),
+ * });
+ * ```
+ *
+ * @category GraphQL
+ */
 declare function FieldLibrary<X extends object, T extends Record<string, FieldResolverDefinition<any, any, X, any, any, any, any>> = Record<string, FieldResolverDefinition<any, any, X, any, any, any, any>>>(type: ClassType, queries: T): {
     new (): {};
 };
+/**
+ * Infers the TypeScript return type of a query definition's `.call()` method.
+ * Use this to type component props that receive query results, ensuring full type safety.
+ *
+ * @typeParam T - A `QueryDefinition` (the default export from a resolver file created with `query()`).
+ *
+ * @example
+ * ```ts
+ * import type { QueryResponseType } from "naystack/graphql";
+ * import type getCurrentUser from "@/app/api/(graphql)/User/resolvers/get-current-user";
+ * import type getDeal from "@/app/api/(graphql)/Deal/queries/get-deal";
+ *
+ * interface Props {
+ *   user: QueryResponseType<typeof getCurrentUser>;
+ *   deal: QueryResponseType<typeof getDeal>;
+ * }
+ * ```
+ *
+ * @category GraphQL
+ */
 type QueryResponseType<T extends QueryDefinition<any, any, any, any, any, any>> = Awaited<ReturnType<T["call"]>>;
+/**
+ * Infers the TypeScript return type of a field resolver definition's `.call()` method.
+ * Use this to type the resolved field value.
+ *
+ * @typeParam T - A `FieldResolverDefinition` (from `field()`).
+ *
+ * @example
+ * ```ts
+ * import type { FieldResponseType } from "naystack/graphql";
+ * import type organizationsField from "./resolvers/organizations-field";
+ *
+ * type Orgs = FieldResponseType<typeof organizationsField>;
+ * ```
+ *
+ * @category GraphQL
+ */
 type FieldResponseType<T extends FieldResolverDefinition<any, any, any, any, any, any, any>> = Awaited<ReturnType<T["call"]>>;
 
 export { FieldLibrary, type FieldResponseType, QueryLibrary, type QueryResponseType, field, query };