crelte 0.5.8 → 0.5.9

package/src/queries/Queries.ts

@@ -91,12 +91,21 @@ export default class Queries {
 		this.request = request;
 	}
 
+	/**
+	 * Create a new Queries instance
+	 *
+	 * @param endpoint the craft GraphQl endpoint
+	 * @param frontend the frontend url where the server queries are reachable
+	 * @param ssrCache the ssrCache to use for caching
+	 * @param opts options
+	 * @returns
+	 */
 	static new(
 		endpoint: string,
 		frontend: string,
 		ssrCache: SsrCache,
 		opts: QueriesOptions = {},
-	) {
+	): Queries {
 		return new Queries(
 			new Inner(endpoint, frontend, ssrCache, opts),
 			opts?.route ?? null,
@@ -131,6 +140,8 @@ export default class Queries {
 		// for convenience we set the siteId as variable if it is known
 		if (siteId !== null) vars = { siteId, ...vars };
 
+		// todo, maybe we should set the XCraftSiteId, with the siteId from vars?
+
 		return this.inner.query(query, vars, {
 			previewToken,
 			siteToken,
@@ -217,16 +228,15 @@ class Inner {
 
 		try {
 			const resp = await this.queryNotCached(query, vars, opts);
+
 			if (key) {
 				// todo maybe we should objClone here?
 				this.ssrCache.set(key, resp);
 
-				// ! because the listeners get's in the previous if statement and will
-				// always be set when the key is set
+				// ! (never null) because the listeners get's in the previous
+				// if statement and will always be set when the key is set
 				const listeners = this.listeners.get(key)!;
-				listeners.forEach(([resolve, _error]) => {
-					resolve(resp);
-				});
+				listeners.forEach(([resolve, _error]) => resolve(resp));
 
 				this.listeners.delete(key);
 			}
@@ -234,12 +244,10 @@ class Inner {
 			return resp;
 		} catch (e: unknown) {
 			if (key) {
-				// ! because the listeners get's in the previous if statement and will
-				// always be set when the key is set
+				// ! (never null) because the listeners get's in the previous
+				// if statement and will always be set when the key is set
 				const listeners = this.listeners.get(key)!;
-				listeners.forEach(([_resolve, error]) => {
-					error(e);
-				});
+				listeners.forEach(([_resolve, error]) => error(e));
 
 				this.listeners.delete(key);
 			}
@@ -291,11 +299,17 @@ class Inner {
 			body = { query: query.query, variables: vars };
 		}
 
-		const resp = await fetch(url, {
-			method: 'POST',
-			headers,
-			body: JSON.stringify(body),
-		});
+		let resp: Response;
+
+		try {
+			resp = await fetch(url, {
+				method: 'POST',
+				headers,
+				body: JSON.stringify(body),
+			});
+		} catch (e: any) {
+			throw new Error(`query to '${url}' failed with: ${e.message}`);
+		}
 
 		if (!resp.ok) {
 			throw new QueryError(
@@ -322,8 +336,11 @@ class Inner {
 		}
 
 		if ('errors' in jsonResp) {
-			console.log(logName + ' errors', jsonResp.errors);
-			throw new QueryError({ status: resp.status }, jsonResp.errors);
+			console.error(logName + ' errors', jsonResp.errors);
+			throw new QueryError(
+				{ status: resp.status, errors: jsonResp.errors },
+				'received errors',
+			);
 		}
 
 		return jsonResp.data ?? null;

package/src/queries/QueryError.ts

@@ -1,6 +1,7 @@
 export type QueryErrorResponse = {
 	status?: number;
 	body?: string;
+	errors?: any[];
 };
 
 // todo improve this
@@ -32,6 +33,14 @@ export default class QueryError extends Error {
 	 * The error message in string form
 	 */
 	get message(): string {
-		return 'QueryError: ' + JSON.stringify(this.resp);
+		return 'QueryError: ' + JSON.stringify(this.resp, null, '  ');
 	}
 }
+
+export function isQueryError(err: any): err is QueryError {
+	return (
+		typeof err === 'object' &&
+		err !== null &&
+		typeof err.__QueryError__ === 'function'
+	);
+}

package/src/queries/gql.ts

@@ -5,8 +5,8 @@ import { isQuery, Query } from './Queries.js';
  * @param strings
  * @param keys
  *
- * ## Example
- * ```
+ * #### Example
+ * ```js
  * const query = gql`query ($id: ID!) { page(id: $id) { id } }`;
  * ```
  */

package/src/queries/index.ts

@@ -5,7 +5,7 @@ import Queries, {
 	QueryOptions,
 } from '../queries/Queries.js';
 import { gql } from './gql.js';
-import QueryError from './QueryError.js';
+import QueryError, { QueryErrorResponse } from './QueryError.js';
 import { QueryVar, ValidIf, vars, varsIdsEqual } from './vars.js';
 
 export {
@@ -15,6 +15,7 @@ export {
 	type Query,
 	isQuery,
 	QueryError,
+	type QueryErrorResponse,
 	gql,
 	vars,
 	type ValidIf,
@@ -22,14 +23,16 @@ export {
 	varsIdsEqual,
 };
 
-type InferQueryVarType<T> = T extends QueryVar<infer U> ? U : never;
+/** @hidden */
+export type InferQueryVarType<T> = T extends QueryVar<infer U> ? U : never;
 
-type InferVariableTypes<T> = {
+/** @hidden */
+export type InferVariableTypes<T> = {
 	[K in keyof T]: InferQueryVarType<T[K]>;
 };
 
 /**
- * ## Example
+ * #### Example
  * ```ts
  * import { vars, Caching } from 'crelte/queries';
  *

package/src/queries/vars.ts

@@ -9,7 +9,7 @@ export const vars = {
 	 * Id is almost the same as number but will also parse
 	 * strings, but only allow non negative integers
 	 *
-	 * ## Warning
+	 * #### Warning
 	 * Ids are not automatically safe to be cached
 	 * you need to validate the response to make sure filters
 	 * with this id returned something
@@ -24,7 +24,7 @@ export const vars = {
 	 *
 	 * The numbers are always unique and sorted in ascending order
 	 *
-	 * ## Warning
+	 * #### Warning
 	 * Ids are not automatically safe to be cached, it is also not
 	 * enough to just check if the filter returned some results.
 	 * Since for example a `relatedTo` filter works like an `or` and
@@ -180,7 +180,11 @@ export class QueryVar<T = any> {
 }
 
 export function isQueryVar(v: any): v is QueryVar {
-	return v && typeof v === 'object' && typeof v.__QueryVar__ === 'function';
+	return (
+		typeof v === 'object' &&
+		v !== null &&
+		typeof v.__QueryVar__ === 'function'
+	);
 }
 
 // does not do string to number conversion
@@ -194,8 +198,8 @@ function isValidId(id: any): id is number {
  * The first argument needs to come from a `vars.ids()` variable.
  * The second argument should come from a query, where the output is trusted.
  *
- * ## Example
- * ```
+ * #### Example
+ * ```js
  * export const variables = {
  *     categories: vars.ids()
  * };
@@ -206,15 +210,15 @@ function isValidId(id: any): id is number {
  * };
  * ```
  *
- * ## Note
+ * #### Note
  * The following cases are considered equal:
- * ```
+ * ```js
  * varsIdsEqual(null, null);
  * varsIdsEqual([], null);
  * varsIdsEqual([1,2], ['2',1]);
  * ```
  * These are not equal:
- * ```
+ * ```js
  * varsIdsEqual([1], null);
  * varsIdsEqual([2,1], [2,1]); // because the second arg gets ordered
  * ```

package/src/routing/LoadRunner.ts

@@ -52,7 +52,7 @@ export default class LoadRunner {
 	/**
 	 * @returns true if the load was completed
 	 *
-	 * ## Throws
+	 * #### Throws
 	 * if there was an error but not if the request
 	 * was cancelled before
 	 */

package/src/routing/index.ts

@@ -1,22 +1,32 @@
 import Router, { type UpdateRequest } from './router/Router.js';
-import Route, { type RouteOptions } from './route/Route.js';
+import Route, {
+	type TemplateModule,
+	type RouteOptions,
+} from './route/Route.js';
 import Request, {
 	type RequestOptions,
 	type DelayRender,
 } from './route/Request.js';
-import Site from './Site.js';
-import BaseRoute from './route/BaseRoute.js';
+import Site, { type SiteFromGraphQl } from './Site.js';
+import BaseRoute, {
+	type BaseRouteOptions,
+	type RouteOrigin,
+} from './route/BaseRoute.js';
 import { shouldInterceptClick } from './utils.js';
 
 export {
 	Router,
 	UpdateRequest,
 	BaseRoute,
+	BaseRouteOptions,
 	Route,
 	RouteOptions,
+	TemplateModule,
 	Site,
+	SiteFromGraphQl,
 	Request,
 	DelayRender,
 	RequestOptions,
 	shouldInterceptClick,
+	RouteOrigin,
 };

package/src/routing/route/BaseRoute.ts

@@ -22,7 +22,7 @@ export type BaseRouteOptions = {
  * - `'replace'`: is set when a route is replaced via `Router.replaceState`
  * - `'push'`: is set when a route is pushed via `Router.pushState`
  *
- * ## Note
+ * #### Note
  * `replace` and `push` will not call loadData
  */
 export type RouteOrigin =
@@ -45,9 +45,9 @@ export default class BaseRoute {
 	url: URL;
 
 	/**
-	 * The site of the route
+	 * The {@link Site} of the route
 	 *
-	 * ## Note
+	 * #### Note
 	 * In the `beforeRequest` event the site might not match
 	 * the url and could be the default site or one that matches
 	 * the users language.
@@ -59,7 +59,7 @@ export default class BaseRoute {
 	/**
 	 * The scroll position of the current route
 	 *
-	 * ## Note
+	 * #### Note
 	 * This does not have to represent the current scroll position
 	 * should more be used internally.
 	 *
@@ -75,7 +75,7 @@ export default class BaseRoute {
 	index: number;
 
 	/**
-	 * The origin of this route, See [[RouteOrigin]]
+	 * The origin of this route, See {@link RouteOrigin}
 	 */
 	origin: RouteOrigin;
 
@@ -92,7 +92,7 @@ export default class BaseRoute {
 	 * This context is not persistant and should be considered "valid"
 	 * only for the current request / route
 	 *
-	 * ## Note
+	 * #### Note
 	 * Consider using state instead. This will not be cloned in the clone
 	 * call so will always be the same object
 	 */
@@ -117,8 +117,8 @@ export default class BaseRoute {
 	 *
 	 * Never ends with a slash
 	 *
-	 * ## Example
-	 * ```
+	 * #### Example
+	 * ```js
 	 * const site = _; // site with url https://example.com/fo
 	 * const route = new Route('https://example.com/foo/bar/', site);
 	 * console.log(route.uri); // '/bar'
@@ -143,8 +143,8 @@ export default class BaseRoute {
 	 *
 	 * Never ends with a slash
 	 *
-	 * ## Example
-	 * ```
+	 * #### Example
+	 * ```js
 	 * const site = _; // site with url https://example.com/foo
 	 * const route = new Route('https://example.com/foo/bar/', null);
 	 * console.log(route.baseUrl); // 'https://example.com/foo'
@@ -163,11 +163,11 @@ export default class BaseRoute {
 	/**
 	 * Returns the search params
 	 *
-	 * ## Note
+	 * #### Note
 	 * You might also have a look at `getSearchParam` and `setSearchParam`
 	 *
-	 * ## Example
-	 * ```
+	 * #### Example
+	 * ```js
 	 * const route = new Route('https://example.com/foo/bar/?a=1&b=2', null);
 	 * console.log(route.search.get('a')); // '1'
 	 * ```
@@ -179,8 +179,8 @@ export default class BaseRoute {
 	/**
 	 * Returns the hash of the route
 	 *
-	 * ## Example
-	 * ```
+	 * #### Example
+	 * ```js
 	 * const route = new Route('https://example.com/foo/bar/#hash', null);
 	 * console.log(route.hash); // '#hash'
 	 * ```
@@ -192,8 +192,8 @@ export default class BaseRoute {
 	/**
 	 * Set the hash of the route
 	 *
-	 * ## Example
-	 * ```
+	 * #### Example
+	 * ```js
 	 * const route = new Route('https://example.com/foo/bar/', null);
 	 * route.hash = '#hash';
 	 * console.log(route.url.href); // 'https://example.com/foo/bar/#hash'
@@ -213,8 +213,8 @@ export default class BaseRoute {
 	/**
 	 * Gets the search param
 	 *
-	 * ## Example
-	 * ```
+	 * #### Example
+	 * ```js
 	 * const route = new Route('https://example.com/foo/bar/?a=1&b=2', null);
 	 * console.log(route.getSearchParam('a')); // '1'
 	 * ```
@@ -227,8 +227,8 @@ export default class BaseRoute {
 	 * Sets the search param or removes it if the value is null, undefined or an
 	 * empty string
 	 *
-	 * ## Example
-	 * ```
+	 * #### Example
+	 * ```js
 	 * const route = new Route('https://example.com/foo/bar/?a=1&b=2', null);
 	 * route.setSearchParam('a', '3');
 	 * console.log(route.url.href); // 'https://example.com/foo/bar/?a=3&b=2'
@@ -261,7 +261,7 @@ export default class BaseRoute {
 	 * Sets a state value.
 	 * If the value is null or undefined, the key will be removed.
 	 *
-	 * ## When to use state
+	 * #### When to use state
 	 * State is used to store additional information that persists across route changes.
 	 * The State is only available in the client code since it is stored using window.history.
 	 *
@@ -286,7 +286,7 @@ export default class BaseRoute {
 	 * Sets a context value.
 	 * If the value is null or undefined, the key will be removed.
 	 *
-	 * ## When to use context
+	 * #### When to use context
 	 * Context is used to pass data to onRoute and onRequest handlers or exchange data between loadData calls.
 	 * This context is not persistent and should be considered valid only for the current request/route.
 	 * The context is not cloned in the clone call and will be the same object.
@@ -324,7 +324,7 @@ export default class BaseRoute {
 	 * This checks the url but search params do not have to be in the
 	 * same order
 	 *
-	 * ## Note
+	 * #### Note
 	 * This only check the url, not site or anything else.
 	 */
 	eq(route: BaseRoute | null) {
@@ -380,7 +380,7 @@ export default class BaseRoute {
 	/**
 	 * Create a copy of the Route
 	 *
-	 * ## Note
+	 * #### Note
 	 * This does not make a copy of the template or context
 	 */
 	clone() {

package/src/routing/route/Request.ts

@@ -107,12 +107,12 @@ export default class Request extends BaseRoute {
 	 * With delayRender you can make sure that the render waits
 	 * until you are ready. This is useful for building page transitions.
 	 *
-	 * ## Important
+	 * #### Important
 	 * If you call delayRender you need to call `ready/remove` or the render
 	 * will never happen
 	 *
-	 * ## Example
-	 * ```
+	 * #### Example
+	 * ```js
 	 * import { onRequest } from 'crelte';
 	 * import { animate } from 'motion';
 	 *
@@ -175,7 +175,7 @@ export default class Request extends BaseRoute {
 	/**
 	 * Create a Route from the Request
 	 *
-	 * ## Throws
+	 * #### Throws
 	 * if the entry, template or loadedData is missing
 	 * or the request was cancelled
 	 */

package/src/routing/route/Route.ts

@@ -48,7 +48,7 @@ export default class Route extends BaseRoute {
 	/**
 	 * Create a new Route
 	 *
-	 * ## Note
+	 * #### Note
 	 * This should only be created by crelte
 	 */
 	constructor(
@@ -70,7 +70,7 @@ export default class Route extends BaseRoute {
 	/**
 	 * Create a copy of the EntryRoute
 	 *
-	 * ## Note
+	 * #### Note
 	 * This does not make a copy of the entry, template or loadedData.
 	 */
 	clone() {

package/src/routing/router/BaseRouter.ts

@@ -25,7 +25,7 @@ export default class BaseRouter {
 	/**
 	 * The current route
 	 *
-	 * ## Note
+	 * #### Note
 	 * Will always contain a route except in the first loadData call
 	 */
 	route: Writable<Route | null>;
@@ -34,7 +34,7 @@ export default class BaseRouter {
 	/**
 	 * The current site
 	 *
-	 * ## Note
+	 * #### Note
 	 * Will always contain a site except in the first loadData call
 	 */
 	site: Writable<Site | null>;
@@ -79,7 +79,7 @@ export default class BaseRouter {
 	onRender: (
 		cr: CrelteRequest,
 		/**
-		 * ## Throws
+		 * #### Throws
 		 * if the route is missing entry, template or loadedData
 		 */
 		readyForRoute: () => Route,
@@ -252,7 +252,7 @@ export default class BaseRouter {
 	}
 
 	/**
-	 * ## Throws
+	 * #### Throws
 	 * If the request completed but had an error
 	 */
 	async handleRequest(

package/src/routing/router/ClientRouter.ts

@@ -24,7 +24,7 @@ export default class ClientRouter extends BaseRouter {
 	}
 
 	/**
-	 * ## Throws
+	 * #### Throws
 	 */
 	async init() {
 		this.listen();

package/src/routing/router/Router.ts

@@ -9,26 +9,29 @@ import { Entry } from '../../loadData/index.js';
  *
  * If you return `false` the request will be aborted
  *
- * ## Example
- * ```
+ * #### Example
+ * ```js
  * router.replace(req => (req.hash = ''));
  * ```
  */
 export type UpdateRequest = (req: Request) => boolean | null | undefined | void;
 
+/**
+ * The Crelte Router
+ */
 export default class Router {
 	private inner: BaseRouter;
 	private _request: Request | null;
 
-	constructor(inner: BaseRouter) {
-		this.inner = inner;
+	constructor(inner: any) {
+		this.inner = inner as BaseRouter;
 		this._request = null;
 	}
 
 	/**
 	 * returns a store with the current route
 	 *
-	 * ## Note
+	 * #### Note
 	 * Will always contain a route except in the first loadData call this
 	 * is intentional since you will get the wrong route in a loadData call.
 	 * In a loadData you should always use the `CrelteRequest` provided
@@ -41,10 +44,10 @@ export default class Router {
 	/**
 	 * returns a store with the current site
 	 *
-	 * ## Note
+	 * #### Note
 	 * Will always contain a site except in the first loadData call this
 	 * is intentional since you might get the wrong site if a site switch
-	 * is happening and you call this in loadData. If possible use the CrelteRequest
+	 * is happening and you call this in loadData. If possible use the {@link CrelteRequest#site}
 	 * provided in each loadData call.
 	 *
 	 * Else use `router.site.get() ?? router.req.site`
@@ -56,7 +59,7 @@ export default class Router {
 	/**
 	 * returns a store with the current entry
 	 *
-	 * ## Note
+	 * #### Note
 	 * Will always contain an entry except in the first loadData call this
 	 * is intentional since you might get the wrong entry if a request is happening
 	 * and you call this in loadData. If possible use the CrelteRequest
@@ -69,8 +72,8 @@ export default class Router {
 	/**
 	 * returns the latest request in progress otherwise returns null.
 	 *
-	 * ## Important !!
-	 * If at all possible prefer using the `CrelteRequest` provided in each
+	 * #### Important !!
+	 * If at all possible prefer using the {@link CrelteRequest} provided in each
 	 * loadData call. For example in a preload request this will return null.
 	 * Or a user has clicked multiple times on different links you might get
 	 * the url of the newer request.
@@ -121,7 +124,7 @@ export default class Router {
 	}
 
 	/**
-	 * Returns a site which is preffered based on the users language
+	 * Returns a site which is preferred based on the users language
 	 *
 	 * Returns null if no site could be determined
 	 */
@@ -136,11 +139,11 @@ export default class Router {
 	 * the url needs to start with http or with a / which will be considered as
 	 * the site baseUrl
 	 *
-	 * ## Note
+	 * #### Note
 	 * The origin will always be set to 'manual'
 	 *
-	 * ## Example
-	 * ```
+	 * #### Example
+	 * ```js
 	 * import { getRouter } from 'crelte';
 	 *
 	 * const router = getRouter();
@@ -181,13 +184,13 @@ export default class Router {
 	 * You can use this when using pagination for example change the route object
 	 * (search argument) and then call push
 	 *
-	 * ## Note
+	 * #### Note
 	 * This will always set the origin to 'push'
 	 * And will clear the scrollY value if you dont provide a new one via the `opts`
 	 * This will disableLoadData by default if you dont provide an override via the `opts`
 	 *
-	 * ## Example using the update function
-	 * ```
+	 * #### Example using the update function
+	 * ```js
 	 * import { getRouter } from 'crelte';
 	 *
 	 * const router = getRouter();
@@ -196,8 +199,8 @@ export default class Router {
 	 * router.push(req => req.setSearchParam('page', page || null));
 	 * ```
 	 *
-	 * ## Example using the route object
-	 * ```
+	 * #### Example using the route object
+	 * ```js
 	 * import { getRouter } from 'crelte';
 	 *
 	 * const router = getRouter();
@@ -244,13 +247,13 @@ export default class Router {
 	 *
 	 * You can use this when using some filters for example a search filter
 	 *
-	 * ## Note
+	 * #### Note
 	 * This will always set the origin to 'replace'
 	 * And will clear the scrollY value if you don't provide a new one via the `opts`
 	 * This will disableLoadData by default if you don't provide an override via the `opts`
 	 *
-	 * ## Example using the update function
-	 * ```
+	 * #### Example using the update function
+	 * ```js
 	 * import { getRouter } from 'crelte';
 	 *
 	 * const router = getRouter();
@@ -259,8 +262,8 @@ export default class Router {
 	 * router.replace(req => req.setSearchParam('search', search));
 	 * ```
 	 *
-	 * ## Example using the route object
-	 * ```
+	 * #### Example using the route object
+	 * ```js
 	 * import { getRouter } from 'crelte';
 	 *
 	 * const router = getRouter();
@@ -355,7 +358,7 @@ export default class Router {
 	 * Resolve a url or Route and convert it to a Request
 	 *
 	 * @param target
-	 * @param opts, any option present will override the value in target
+	 * @param opts any option present will override the value in target
 	 * @return Returns null if the url does not match our host (the protocol get's ignored)
 	 */
 	targetToRequest(