crelte 0.5.7 → 0.5.9

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(

package/src/routing/router/ServerRouter.ts

@@ -67,7 +67,7 @@ export default class ServerRouter extends BaseRouter {
 	 *
 	 * And then if no redirect happen the final route
 	 *
-	 * ## Throws
+	 * #### Throws
 	 * If the request fails
 	 */
 	async init(url: string): Promise<[Request, Route | null]> {

package/src/server/CrelteServer.ts

@@ -15,7 +15,7 @@ export type CrelteServerRequestOptions = {
 
 export default class CrelteServerRequest {
 	/**
-	 * The current request
+	 * The current request {@link ServerRequest}
 	 */
 	req: ServerRequest;
 
@@ -24,7 +24,7 @@ export default class CrelteServerRequest {
 	private _sites: Site[];
 	private _langs: string[];
 	private _queries: Queries;
-	protected _cookies: Cookies;
+	private _cookies: Cookies;
 
 	constructor(req: ServerRequest, opts: CrelteServerRequestOptions) {
 		this.req = req;
@@ -43,7 +43,7 @@ export default class CrelteServerRequest {
 	/**
 	 * Easy access to this.req.site
 	 *
-	 * ## Note
+	 * #### Note
 	 * The site might not always match with the current route
 	 * but be the site default site or one that matches the
 	 * users language.
@@ -94,7 +94,7 @@ export default class CrelteServerRequest {
 	/**
 	 * returns the frontend url with an optional path
 	 *
-	 * ## Note
+	 * #### Note
 	 * For the origin the `FRONTEND_URL` env variable is used
 	 */
 	frontendUrl(path?: string): URL {
@@ -104,7 +104,7 @@ export default class CrelteServerRequest {
 	/**
 	 * returns the backend url with an optional path
 	 *
-	 * ## Note
+	 * #### Note
 	 * For the origin the `ENDPOINT_URL` env variable is used
 	 */
 	backendUrl(path?: string): URL {

package/src/server/Request.ts

@@ -1,12 +1,18 @@
 import { Site } from '../routing/index.js';
 
+/**
+ * Extended Request class for server requests
+ *
+ * This extends the WebApi [Request](https://developer.mozilla.org/docs/Web/API/Request)
+ * and adds three properties {@link site}, {@link getParam} and {@link siteMatches}.
+ */
 export default class ServerRequest extends Request {
 	private params: Map<string, string>;
 
 	/**
 	 * The site of the route
 	 *
-	 * ## Note
+	 * #### Note
 	 * The site might not always match with the current route
 	 * but be the site default site or one that matches the
 	 * users language.

package/src/server/ServerRouter.ts

@@ -1,12 +1,11 @@
 import { Methods, Pattern, Trouter } from 'trouter';
 import CrelteServerRequest from './CrelteServer.js';
 import ServerRequest from './Request.js';
-import { SiteFromGraphQl } from './shared.js';
 import { Queries, Query, QueryOptions } from '../queries/index.js';
 import { Site } from '../routing/index.js';
 import { SsrCache } from '../ssr/index.js';
 import { parseAcceptLanguage } from '../std/intl/index.js';
-import { siteFromUrl } from '../routing/Site.js';
+import { SiteFromGraphQl, siteFromUrl } from '../routing/Site.js';
 import { preferredSite } from '../routing/utils.js';
 
 export type Handler = (

package/src/server/index.ts

@@ -1,9 +1,16 @@
 import ServerRequest from './Request.js';
-import ServerRouter, { Handler } from './ServerRouter.js';
-import CrelteServerRequest from './CrelteServer.js';
+import ServerRouter, {
+	type RouterOptions,
+	type Handler,
+} from './ServerRouter.js';
+import CrelteServerRequest, {
+	type CrelteServerRequestOptions,
+} from './CrelteServer.js';
 
 export {
 	type ServerData,
+	type RenderRequest,
+	type RenderResponse,
 	type MainData,
 	main,
 	type Error,
@@ -11,4 +18,11 @@ export {
 	mainError,
 } from '../init/server.js';
 
-export { CrelteServerRequest, ServerRouter, type Handler, ServerRequest };
+export {
+	CrelteServerRequest,
+	CrelteServerRequestOptions,
+	ServerRouter,
+	RouterOptions,
+	Handler,
+	ServerRequest,
+};

package/src/server/queries/queries.ts

@@ -1,6 +1,6 @@
 import ServerRouter from '../ServerRouter.js';
 import QueriesCaching from './QueriesCaching.js';
-import { CacheIfFn, QueryRoute } from './routes.js';
+import { CacheIfFn, QueryRoute, TransformFn } from './routes.js';
 import { isQueryVar, QueryVar } from '../../queries/vars.js';
 import { Platform } from '../platform.js';
 
@@ -10,8 +10,9 @@ type ModQuery = {
 };
 
 type ModTs = {
-	variables: any;
+	variables?: any;
 	caching?: any;
+	transform?: any;
 };
 
 type ModQueries = Record<string, ModQuery | ModTs>;
@@ -21,6 +22,8 @@ type PreRoute = {
 	jsFile: string | null;
 	vars: Record<string, QueryVar> | null;
 	cacheIfFn: CacheIfFn | null;
+	preventCaching: boolean;
+	transformFn: TransformFn | null;
 };
 
 export async function initQueryRoutes(
@@ -51,6 +54,8 @@ export async function initQueryRoutes(
 				jsFile: null,
 				vars: null,
 				cacheIfFn: null,
+				preventCaching: false,
+				transformFn: null,
 			};
 			preRoutes.set(name, preRoute);
 		}
@@ -75,6 +80,12 @@ export async function initQueryRoutes(
 
 		if (mts.caching) {
 			preRoute.cacheIfFn = parseCaching(mts.caching);
+		} else if (typeof mts.caching === 'boolean') {
+			preRoute.preventCaching = true;
+		}
+
+		if (mts.transform) {
+			preRoute.transformFn = parseTransform(mts.transform);
 		}
 	}
 
@@ -85,7 +96,7 @@ export async function initQueryRoutes(
 	for (const [name, pr] of preRoutes.entries()) {
 		if (!pr.query) throw new Error(`no .graphql file for query ${name}`);
 
-		const route = new QueryRoute(name, pr.query, pr.vars, pr.cacheIfFn);
+		const route = new QueryRoute(name, pr.query, pr);
 
 		router.post('/queries/' + route.name, async csr =>
 			route.handle(caching, csr),
@@ -119,3 +130,10 @@ function parseCaching(caching: any): CacheIfFn {
 
 	return caching;
 }
+
+function parseTransform(transform: any): TransformFn {
+	if (typeof transform !== 'function')
+		throw new Error('transform should be a function');
+
+	return transform;
+}

package/src/server/queries/routes.ts

@@ -7,30 +7,50 @@ import { calcKey } from '../../ssr/index.js';
 
 export type CacheIfFn = (response: any, vars: Record<string, any>) => boolean;
 
+/// Anything other than returning undefined will replace the response
+//
+// Note that even if you return undefined since the response is by reference
+// you're modifications will be reflected
+export type TransformFn = (
+	response: any,
+	vars: Record<string, any>,
+) => void | any | Promise<void | any>;
+
+export type QueryRouteArgs = {
+	vars: Record<string, QueryVar> | null;
+	cacheIfFn: CacheIfFn | null;
+	preventCaching: boolean;
+	transformFn: TransformFn | null;
+};
+
 // only internal
 export class QueryRoute {
 	name: string;
 	query: string;
 	vars: Record<string, QueryVar> | null;
 	cacheIfFn: CacheIfFn | null;
+	transformFn: TransformFn | null;
 
-	constructor(
-		name: string,
-		query: string,
-		vars: Record<string, QueryVar> | null,
-		cacheIfFn: CacheIfFn | null,
-	) {
-		if (cacheIfFn && !vars)
+	constructor(name: string, query: string, args: QueryRouteArgs) {
+		if (args.cacheIfFn && !vars)
 			throw new Error(
 				'queryRoute: ' +
 					name +
-					' cannot have cacheIfFn if there are no vars defined',
+					' cannot have caching function if there are no ' +
+					'variables defined',
 			);
 
 		this.name = name;
 		this.query = query;
-		this.vars = vars;
-		this.cacheIfFn = cacheIfFn;
+		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();
@@ -96,6 +116,16 @@ export class QueryRoute {
 		return nVars;
 	}
 
+	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,
@@ -187,6 +217,7 @@ export class QueryRoute {
 			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);
 		}