crelte 0.5.10 → 0.5.11

package/src/plugins/Events.ts

@@ -40,7 +40,7 @@ export default class Events {
 	): () => void;
 	on(
 		ev: 'loadGlobalData',
-		fn: (cr: CrelteRequest) => Promise<any>,
+		fn: (cr: CrelteRequest) => Promise<any> | any,
 	): () => void;
 	on(
 		ev: 'loadEntry',
@@ -52,11 +52,11 @@ export default class Events {
 	): () => void;
 	on(
 		ev: 'afterLoadEntry',
-		fn: (cr: CrelteRequest) => Promise<any>,
+		fn: (cr: CrelteRequest) => Promise<any> | any,
 	): () => void;
 	on(
 		ev: 'loadData',
-		fn: (cr: CrelteRequest, entry: Entry) => Promise<any>,
+		fn: (cr: CrelteRequest, entry: Entry) => Promise<any> | any,
 	): () => void;
 	on(ev: 'beforeRender', fn: (cr: CrelteRequest) => void): () => void;
 	on(ev: string, fn: (...args: any[]) => any): () => void {
@@ -95,14 +95,18 @@ export default class Events {
 	 * Trigger an event
 	 */
 	trigger(ev: 'beforeRequest', cr: CrelteRequest): (Promise<void> | void)[];
-	trigger(ev: 'loadGlobalData', cr: CrelteRequest): Promise<any>[];
+	trigger(ev: 'loadGlobalData', cr: CrelteRequest): (Promise<any> | any)[];
 	trigger(
 		ev: 'beforeQueryEntry',
 		cr: CrelteRequest,
 		vars: EntryQueryVars,
 	): (Promise<void> | void)[];
-	trigger(ev: 'afterLoadEntry', cr: CrelteRequest): Promise<any>[];
-	trigger(ev: 'loadData', cr: CrelteRequest, entry: Entry): Promise<any>[];
+	trigger(ev: 'afterLoadEntry', cr: CrelteRequest): (Promise<any> | any)[];
+	trigger(
+		ev: 'loadData',
+		cr: CrelteRequest,
+		entry: Entry,
+	): (Promise<any> | any)[];
 	trigger(ev: 'beforeRender', cr: CrelteRequest, route: Route): void[];
 	trigger(ev: string, ...args: any[]): any[] {
 		const set = this.inner.get(ev);

package/src/queries/Queries.ts

@@ -17,17 +17,35 @@ export type QueriesOptions = {
 /**
  * A GraphQL query
  *
- * You should almost never create this object directly
- * but instead import a graphql file or use the gql template.
+ * **You should almost never**
+ *
+ * When importing a graphql file you will get a {@link NamedQuery}
+ * or use the {@link gql} template function to create
+ * an {@link InlineQuery}.
+ * Alternatively you can use the {@link namedQuery} function to create
+ * a {@link NamedQuery}.
+ */
+export type Query = InlineQuery | NamedQuery;
+
+/**
+ * You should never create this type directly. It is returned from
+ * the {@link gql} template function.
+ */
+export type InlineQuery = { path?: string; query: string };
+
+/**
+ * Always create this object via the {@link namedQuery} function
+ */
+export type NamedQuery = { queryName: string };
+
+/**
+ * Create a NamedQuery for the given server query name.
+ *
+ * Prefer importing a graphql file instead.
  */
-export type Query =
-	| {
-			path?: string;
-			query: string;
-	  }
-	| {
-			queryName: string;
-	  };
+export function namedQuery(name: string): NamedQuery {
+	return { queryName: name };
+}
 
 /** Returns true if the passed object is a GraphQlQuery */
 export function isQuery(obj: any): obj is Query {
@@ -102,8 +120,8 @@ export default class Queries {
 	 */
 	static new(
 		endpoint: string,
-		frontend: string,
-		ssrCache: SsrCache,
+		frontend: string | null = null,
+		ssrCache: SsrCache = new SsrCache(),
 		opts: QueriesOptions = {},
 	): Queries {
 		return new Queries(
@@ -113,6 +131,18 @@ export default class Queries {
 		);
 	}
 
+	/**
+	 * Create a new Queries instance that always intented to call an
+	 * external GraphQl endpoint.
+	 */
+	static newExternal(endpoint: string, bearerToken?: string): Queries {
+		return new Queries(
+			new Inner(endpoint, null, new SsrCache(), { bearerToken }),
+			null,
+			null,
+		);
+	}
+
 	/**
 	 * Run a GraphQl Query
 	 *
@@ -170,7 +200,7 @@ type InnerQueryOptions = {
 
 class Inner {
 	endpoint: string;
-	frontend: string;
+	frontend: string | null;
 	ssrCache: SsrCache;
 	private listeners: Map<
 		string,
@@ -184,7 +214,7 @@ class Inner {
 
 	constructor(
 		endpoint: string,
-		frontend: string,
+		frontend: string | null,
 		ssrCache: SsrCache,
 		opts: QueriesOptions = {},
 	) {
@@ -264,6 +294,9 @@ class Inner {
 		let logName: string, url: URL;
 
 		if ('queryName' in query) {
+			if (!this.frontend)
+				throw new Error('only inline queries supported');
+
 			logName = `query (server: ${query.queryName})`;
 			url = new URL(this.frontend);
 			url.pathname = '/queries/' + query.queryName;

package/src/queries/gql.ts

@@ -1,4 +1,4 @@
-import { isQuery, Query } from './Queries.js';
+import { InlineQuery, isQuery } from './Queries.js';
 
 /**
  * Create a GraphQL query string with variables.
@@ -13,7 +13,7 @@ import { isQuery, Query } from './Queries.js';
 export function gql(
 	strings: TemplateStringsArray | string[] | string,
 	...keys: unknown[]
-): Query {
+): InlineQuery {
 	if (typeof strings === 'string') strings = [strings];
 
 	let query = '';

package/src/queries/index.ts

@@ -1,9 +1,13 @@
 import Queries, {
+	InlineQuery,
 	isQuery,
+	namedQuery,
+	NamedQuery,
 	QueriesOptions,
 	Query,
 	QueryOptions,
 } from '../queries/Queries.js';
+import type CrelteServerRequest from '../server/CrelteServer.js';
 import { gql } from './gql.js';
 import QueryError, { QueryErrorResponse } from './QueryError.js';
 import { QueryVar, ValidIf, vars, varsIdsEqual } from './vars.js';
@@ -13,6 +17,9 @@ export {
 	type QueriesOptions,
 	type QueryOptions,
 	type Query,
+	type InlineQuery as GqlQuery,
+	type NamedQuery,
+	namedQuery,
 	isQuery,
 	QueryError,
 	type QueryErrorResponse,
@@ -32,6 +39,8 @@ export type InferVariableTypes<T> = {
 };
 
 /**
+ * Defines when a query can safely be cached.
+ *
  * #### Example
  * ```ts
  * import { vars, Caching } from 'crelte/queries';
@@ -48,3 +57,65 @@ export type InferVariableTypes<T> = {
 export type Caching<
 	T extends Record<string, QueryVar<any>> = Record<string, QueryVar<any>>,
 > = boolean | ((response: any, vars: InferVariableTypes<T>) => boolean);
+
+/** use {@link Transfrom} */
+export type TransformFn<
+	T extends Record<string, QueryVar<any>> = Record<string, QueryVar<any>>,
+> = (
+	response: any,
+	vars: InferVariableTypes<T>,
+) => void | any | Promise<void | any>;
+
+/**
+ * Transforms the query response before it is returned or cached.
+ *
+ * #### Example
+ * ```ts
+ * export const transform: Transform<typeof variables> = (response, vars) => {
+ *     for (const entry of response.entries) {
+ *         entry.title = entry.title.toUpperCase();
+ *     }
+ * };
+ * ```
+ */
+export type Transform<
+	T extends Record<string, QueryVar<any>> = Record<string, QueryVar<any>>,
+	F extends TransformFn<T> = TransformFn<T>,
+> = (response: any, vars: InferVariableTypes<T>) => Awaited<ReturnType<F>>;
+
+/** use {@link Handle} */
+export type HandleFn<
+	T extends Record<string, QueryVar<any>> = Record<string, QueryVar<any>>,
+> = (csr: CrelteServerRequest, vars: InferVariableTypes<T>) => any;
+
+/**
+ * Handles a query request.
+ *
+ * #### Example
+ * ```ts
+ * // queries/custom.ts
+ * import { vars, type Handle, gql, namedQuery } from 'crelte/queries';
+ *
+ * // It is good practice to have the query name inside the file
+ * export const customQuery = namedQuery('custom');
+ *
+ * export const variables = {
+ *     name: vars.string(),
+ * };
+ *
+ * export const handle: Handle<typeof variables> = async (csr, vars) => {
+ *     if (vars.name === 'demo') {
+ *         throw new Response('not allowed', { status: 400 });
+ *     }
+ *
+ *     return { name: vars.name };
+ * };
+ * ```
+ */
+export type Handle<
+	T extends Record<string, QueryVar<any>> = Record<string, QueryVar<any>>,
+	F extends HandleFn<T> = HandleFn<T>,
+> = (
+	csr: CrelteServerRequest,
+	vars: InferVariableTypes<T>,
+) => Awaited<ReturnType<F>>;

package/src/queries/vars.ts

@@ -53,12 +53,14 @@ export class QueryVar<T = any> {
 	private name: string | null;
 	private type: 'any' | 'string' | 'number' | 'id' | 'ids';
 	private flagNullable: boolean;
+	private defaultValue: T | undefined;
 	private validIfFn: ValidIf<T>;
 
 	constructor() {
 		this.name = null;
 		this.type = 'any';
 		this.flagNullable = false;
+		this.defaultValue = undefined;
 		this.validIfFn = () => true;
 	}
 
@@ -87,6 +89,11 @@ export class QueryVar<T = any> {
 		return this as QueryVar<T | null>;
 	}
 
+	default(value: T): QueryVar<T> {
+		this.defaultValue = value;
+		return this;
+	}
+
 	/**
 	 * Set a validation function for this variable
 	 *
@@ -103,6 +110,8 @@ export class QueryVar<T = any> {
 		if (typeof v === 'undefined') v = null;
 
 		if (v === null) {
+			if (this.defaultValue !== undefined) return this.defaultValue;
+
 			if (!this.flagNullable)
 				throw new Error(`variable ${this.name} cannot be null`);
 
@@ -139,7 +148,11 @@ export class QueryVar<T = any> {
 					);
 
 				if (v.length <= 0) {
+					if (this.defaultValue !== undefined)
+						return this.defaultValue;
+
 					if (this.flagNullable) return null;
+
 					throw new Error(
 						`variable ${this.name} is not allowed to be empty`,
 					);

package/src/routing/router/BaseRouter.ts

@@ -123,8 +123,10 @@ export default class BaseRouter {
 	}
 
 	/**
-	 * todo check that the router uses the correct sites for each function
+	 * Returns the default site tries to use a site which matches the preferred language
+	 * else returns the primary site
 	 */
+	// todo check that the router uses the correct sites for each function
 	defaultSite(): Site {
 		return this.preferredSite() ?? this.primarySite();
 	}
@@ -233,7 +235,7 @@ export default class BaseRouter {
 		const req = this.targetToRequest(target, { origin: 'preload' });
 		const current = this.route.get();
 
-		// if the origin matches, the route will be able to be load
+		// if the origin matches, the route will be able to be loaded
 		// so let's preload it
 		if (current && current.url.origin === req.url.origin) {
 			// todo i don't wan't to send a CrelteRequest?

package/src/routing/router/ClientRouter.ts

@@ -202,11 +202,10 @@ export default class ClientRouter extends BaseRouter {
 		window.addEventListener('scroll', () => this.onScroll());
 
 		window.addEventListener('popstate', async e => {
-			if (!e.state?.route) return;
-
-			const req = this.targetToRequest(window.location.href);
+			const req = this.targetToRequest(window.location.href, {
+				origin: 'pop',
+			});
 			req.z_fillFromState(e.state);
-			req.origin = 'pop';
 
 			// todo handle errors
 			this.handleRequest(req, () => {});

package/src/routing/router/Router.ts

@@ -409,7 +409,8 @@ export default class Router {
 		return nRouter;
 	}
 
-	_requestCompleted() {
+	/** @hidden */
+	z_requestCompleted() {
 		this._request = null;
 	}
 }

package/src/routing/utils.ts

@@ -5,7 +5,7 @@ export function trimSlashEnd(str: string) {
 	return str.endsWith('/') ? str.substring(0, str.length - 1) : str;
 }
 
-// same as ?? but only for undefined
+/** same as ?? but only for undefined */
 export function orDef<T>(a: T | undefined, def: T): T {
 	return a === undefined ? def : a;
 }

package/src/server/ServerRouter.ts

@@ -139,9 +139,7 @@ export default class ServerRouter {
 			this.endpointUrl,
 			this.frontendUrl,
 			new SsrCache(),
-			{
-				bearerToken: this.endpointToken,
-			},
+			{ bearerToken: this.endpointToken },
 		);
 
 		const csr = new CrelteServerRequest(nReq, {
@@ -152,12 +150,25 @@ export default class ServerRouter {
 			queries,
 		});
 
+		let resp: Response | null = null;
 		for (const handler of handlers) {
-			const res = await handler(csr);
-			if (res) {
-				csr.z_finishResponse(res);
-				return res;
+			try {
+				const res = await handler(csr);
+				if (!res) continue;
+
+				resp = res;
+			} catch (e) {
+				if (!(e instanceof Response)) throw e;
+
+				resp = e;
 			}
+
+			break;
+		}
+
+		if (resp) {
+			csr.z_finishResponse(resp);
+			return resp;
 		}
 
 		return null;

package/src/server/queries/QueryGqlRoute.ts

@@ -0,0 +1,224 @@
+import CrelteServerRequest from '../CrelteServer.js';
+import QueriesCaching from './QueriesCaching.js';
+import { QueryVar, vars } from '../../queries/vars.js';
+import { extractEntry } from '../../loadData/index.js';
+import { calcKey } from '../../ssr/index.js';
+import { CacheIfFn, newError, TransformFn, validateVars } from './routes.js';
+
+export type QueryGqlArgs = {
+	vars: Record<string, QueryVar> | null;
+	cacheIfFn: CacheIfFn | null;
+	preventCaching: boolean;
+	transformFn: TransformFn | null;
+};
+
+// only internal
+export default class QueryGqlRoute {
+	name: string;
+	query: string;
+	vars: Record<string, QueryVar> | null;
+	cacheIfFn: CacheIfFn | null;
+	transformFn: TransformFn | null;
+
+	constructor(name: string, query: string, args: QueryGqlArgs) {
+		if (args.cacheIfFn && !vars)
+			throw new Error(
+				'queryRoute: ' +
+					name +
+					' cannot have caching function if there are no ' +
+					'variables defined',
+			);
+
+		this.name = name;
+		this.query = query;
+		this.vars = args.vars;
+		this.cacheIfFn = args.cacheIfFn;
+		this.transformFn = args.transformFn;
+
+		if (args.preventCaching) {
+			if (this.cacheIfFn) throw new Error('unreachable');
+			// prevent filling defaults
+			return;
+		}
+
+		// add default vars and cacheIfFn if we know the route
+		if (this.name === 'entry') this.fillEntryDefaults();
+		else if (this.name === 'global') this.fillGlobalDefaults();
+		else this.fillBasicDefaults();
+	}
+
+	private fillEntryDefaults() {
+		if (this.vars) return;
+
+		// the _setName step happens in parseVars which happens before setting
+		// the defaults, so since we're adding vars here we need to set the name
+		// manually
+		this.vars = {
+			siteId: vars.siteId().z_setName('siteId'),
+			uri: vars.string().z_setName('uri'),
+		};
+		this.cacheIfFn = res => !!extractEntry(res);
+	}
+
+	private fillGlobalDefaults() {
+		if (this.vars) return;
+
+		this.vars = { siteId: vars.siteId().z_setName('siteId') };
+		this.cacheIfFn = () => true;
+	}
+
+	/**
+	 * This adds caching to queries containing `query {` or
+	 * `query ($siteId: [QueryArgument) {` without any additional vars
+	 */
+	private fillBasicDefaults() {
+		if (this.vars) return;
+
+		const NO_VAR_TEST = /(^|\s)query\s*{/;
+		const SITE_ID_VAR_TEST =
+			/(^|\s)query\s*\(\s*\$siteId\s*:\s*\[\s*QueryArgument\s*\]\s*\)\s*{/;
+
+		if (NO_VAR_TEST.test(this.query)) {
+			this.vars = {};
+			this.cacheIfFn = () => true;
+		} else if (SITE_ID_VAR_TEST.test(this.query)) {
+			this.vars = { siteId: vars.siteId().z_setName('siteId') };
+			this.cacheIfFn = () => true;
+		} else if (!this.query.includes('query')) {
+			// this warning might be shown to mutation queries or subscriptions
+			// in that case, the user should explicitly set caching to false
+			console.warn(
+				`cannot determine if query (${this.name}) is cacheable, see` +
+					' https://github.com/crelte/crelte/issues/114 for infos',
+			);
+		}
+	}
+
+	private async transform(
+		jsonResp: Record<string, any>,
+		vars: Record<string, any>,
+	): Promise<void> {
+		if (!this.transformFn || !jsonResp.data) return;
+
+		const transformed = await this.transformFn(jsonResp.data, vars);
+		if (typeof transformed !== 'undefined') jsonResp.data = transformed;
+	}
+
+	async handle(
+		caching: QueriesCaching,
+		csr: CrelteServerRequest,
+	): Promise<Response> {
+		let vars: Record<string, any>;
+		try {
+			const reqVars = await csr.req.json();
+			vars = validateVars(this.vars, reqVars, caching.router);
+			if ('qName' in vars || 'xCraftSite' in vars)
+				throw new Error(
+					'qName and xCraftSite are reserved variable names',
+				);
+		} catch (e) {
+			return newError(e, 400);
+		}
+
+		let logInfo: string | null = null;
+		if (caching.debug) {
+			logInfo = `[queries: ${this.name}] vars: ${JSON.stringify(vars)}`;
+		}
+
+		let previewToken: string | null = null;
+		let siteToken: string | null = null;
+
+		const reqSearch = new URL(csr.req.url).searchParams;
+
+		if (reqSearch.has('token')) {
+			previewToken = reqSearch.get('token');
+		} else if (reqSearch.has('siteToken')) {
+			siteToken = reqSearch.get('siteToken');
+		}
+
+		// check for x-craft-site header and pass it on
+		const xCraftSite = csr.req.headers.get('X-Craft-Site');
+
+		let cacheKey: string | null = null;
+		const useCache = !previewToken && caching.isEnabled();
+		if (useCache) {
+			cacheKey = await calcKey({ ...vars, qName: this.name, xCraftSite });
+			const cached = await caching.getCache(cacheKey);
+
+			if (logInfo) console.log(`${logInfo} ${cached ? 'hit' : 'miss'}`);
+
+			// we found something in the cache
+			if (cached) return Response.json(cached);
+		}
+
+		const headers: Record<string, string> = {
+			'Content-Type': 'application/json',
+		};
+
+		const auth = csr.getEnv('ENDPOINT_TOKEN');
+		if (auth) headers['Authorization'] = 'Bearer ' + auth;
+
+		const url = new URL(csr.getEnv('ENDPOINT_URL'));
+		if (previewToken) url.searchParams.set('token', previewToken);
+		if (siteToken) url.searchParams.set('siteToken', siteToken);
+
+		const xDebug = csr.req.headers.get('X-Debug');
+		if (xDebug) headers['X-Debug'] = xDebug;
+
+		if (xCraftSite) headers['X-Craft-Site'] = xCraftSite;
+
+		// now execute the gql request
+		let resp: Response;
+		try {
+			resp = await fetch(url, {
+				method: 'POST',
+				headers,
+				body: JSON.stringify({
+					query: this.query,
+					variables: vars,
+				}),
+			});
+
+			// if the response is not ok we don't cache anything
+			// and just return the response
+			if (!resp.ok) return resp;
+		} catch (e) {
+			return newError(e, 500);
+		}
+
+		const respHeaders: Record<string, string> = {};
+		const xDebugLink = resp.headers.get('X-Debug-Link');
+		if (xDebugLink) respHeaders['X-Debug'] = xDebugLink;
+
+		let jsonResp: Record<string, any>;
+		try {
+			jsonResp = await resp.json();
+			if (!jsonResp || typeof jsonResp !== 'object')
+				throw new Error('invalid json response');
+			await this.transform(jsonResp, vars);
+		} catch (e) {
+			return newError(e, 500);
+		}
+
+		// also no caching for errors
+		if (jsonResp.errors) {
+			return Response.json(jsonResp, { headers: respHeaders });
+		}
+
+		// now we have a valid json resp.
+		// should we cache it?
+		if (cacheKey && this.cacheIfFn?.(jsonResp.data, vars)) {
+			try {
+				await caching.setCache(cacheKey, jsonResp);
+				if (logInfo) console.log(logInfo + ' set cache');
+			} catch (e) {
+				console.error('could not cache gql response', e);
+			}
+			// if caching is enabled but not used we warn
+		} else if (cacheKey && logInfo) {
+			console.warn('!! ' + logInfo + ' caching not allowed');
+		}
+
+		return Response.json(jsonResp, { headers: respHeaders });
+	}
+}

package/src/server/queries/QueryHandleRoute.ts

@@ -0,0 +1,37 @@
+import { QueryVar } from '../../queries/vars.js';
+import CrelteServerRequest from '../CrelteServer.js';
+import ServerRouter from '../ServerRouter.js';
+import { HandleFn, newError, validateVars } from './routes.js';
+
+// only internal
+export default class QueryHandleRoute {
+	name: string;
+	handleFn: HandleFn;
+	vars: Record<string, QueryVar> | null;
+
+	constructor(
+		name: string,
+		handleFn: HandleFn,
+		vars: Record<string, QueryVar> | null,
+	) {
+		this.name = name;
+		this.handleFn = handleFn;
+		this.vars = vars;
+	}
+
+	async handle(
+		cs: ServerRouter,
+		csr: CrelteServerRequest,
+	): Promise<Response> {
+		let vars: Record<string, any>;
+		try {
+			const reqVars = await csr.req.json();
+			vars = validateVars(this.vars, reqVars, cs);
+		} catch (e) {
+			return newError(e, 400);
+		}
+
+		const res = await this.handleFn(csr, vars);
+		return Response.json({ data: res });
+	}
+}