crelte 0.1.0 → 0.1.2

package/src/graphql/GraphQl.ts

@@ -1,3 +1,4 @@
+import Route from '../routing/Route.js';
 import SsrCache, { calcKey as ssrCacheCalcKey } from '../ssr/SsrCache.js';
 
 export type GraphQlErrorResponse = {
@@ -5,7 +6,21 @@ export type GraphQlErrorResponse = {
 	body?: string;
 };
 
+/**
+ * A GraphQL query
+ *
+ * You should almost never create this object directly
+ * but instead import a graphql file or use the gql template.
+ */
+export interface GraphQlQuery {
+	path?: string;
+	query: string;
+}
+
 // todo improve this
+/**
+ * A GraphQL error
+ */
 export class GraphQlError extends Error {
 	resp: GraphQlErrorResponse;
 	ctx: any;
@@ -18,24 +33,44 @@ export class GraphQlError extends Error {
 		this.ctx = ctx;
 	}
 
+	/**
+	 * The status code of the response
+	 */
 	status(): number {
 		return this.resp?.status ?? 500;
 	}
 
 	__isGraphQlError__() {}
 
+	/**
+	 * The error message in string form
+	 */
 	get message(): string {
 		return 'GraphqlError: ' + JSON.stringify(this.resp);
 	}
 }
 
+/**
+ * Options for the GraphQl class
+ */
 export type GraphQlOptions = {
 	debug?: boolean;
 	debugTiming?: boolean;
 };
 
+/**
+ * Options to configure the request
+ *
+ * If you use `Crelte*.query` the following options
+ * will be set automatically:
+ * - path
+ * - route
+ * - previewToken
+ * - siteToken
+ */
 export type GraphQlRequestOptions = {
 	path?: string;
+	route?: Route;
 	ignoreStatusCode?: boolean;
 	previewToken?: string;
 	siteToken?: string;
@@ -45,6 +80,9 @@ export type GraphQlRequestOptions = {
 	status?: number;
 };
 
+/**
+ * A GraphQL client
+ */
 export default class GraphQl {
 	private endpoint: string;
 	private ssrCache: SsrCache;
@@ -57,9 +95,7 @@ export default class GraphQl {
 	private loggingTiming: boolean;
 
 	/**
-	 * Create a new GraphQL
-	 *
-	 * @param {Object} [opts={}] opts `{ debug: false, debugTiming: false }`
+	 * Create a new GraphQL client
 	 */
 	constructor(
 		endpoint: string,
@@ -74,9 +110,41 @@ export default class GraphQl {
 		this.loggingTiming = opts?.debugTiming ?? false;
 	}
 
+	/**
+	 * Run a GraphQl Query
+	 *
+	 * @param query the default export from a graphql file or the gql`query {}`
+	 * function
+	 * @param variables variables that should be passed to the
+	 * graphql query
+	 */
+	async query(
+		query: GraphQlQuery,
+		variables: Record<string, unknown> = {},
+		opts: GraphQlRequestOptions = {},
+	): Promise<unknown> {
+		if (opts.route) {
+			const search = opts.route.search;
+
+			// todo should variables contain siteId
+			// or maybe gql should detect loadData and add it there
+			// it might make export const loadData = query; easier
+
+			if (search.has('token') && search.get('x-craft-live-preview')) {
+				opts.previewToken = search.get('token')!;
+			} else if (search.has('siteToken')) {
+				opts.siteToken = search.get('siteToken')!;
+			}
+		}
+
+		opts.path = query.path;
+
+		return await this.request(query.query, variables, opts);
+	}
+
 	// returns {} or throws
 	// options: {ignoreStatusCode, previewToken, caching, headers}
-	async request(
+	private async request(
 		query: string,
 		variables: Record<string, unknown> = {},
 		options: GraphQlRequestOptions = {},
@@ -219,38 +287,22 @@ export default class GraphQl {
 	}
 }
 
-export class GraphQlQuery {
-	query: string;
-	path: string;
-
-	constructor(query: string, path: string) {
-		this.query = query;
-		this.path = path;
-	}
-
-	/// doc hidden
-	__GraphQlQuery__() {
-		return true;
-	}
-}
-
 /** Returns true if the passed object is a GraphQlQuery */
 export function isGraphQlQuery(obj: any): obj is GraphQlQuery {
 	return (
-		typeof obj === 'object' &&
-		obj !== null &&
-		typeof obj.__GraphQlQuery__ === 'function'
+		typeof obj === 'object' && obj !== null && typeof obj.query === 'string'
 	);
 }
 
 /**
- * @description Create a GraphQL query string with variables.
+ * Create a GraphQL query string with variables.
  * @param strings
  * @param keys
  *
- * @example
- *
- * const query = gql`query ($id: ID!) { page(id: $id) { id } }`
+ * ## Example
+ * ```
+ * const query = gql`query ($id: ID!) { page(id: $id) { id } }`;
+ * ```
  */
 export function gql(
 	strings: TemplateStringsArray | string[] | string,
@@ -277,5 +329,5 @@ export function gql(
 		}
 	});
 
-	return new GraphQlQuery(query, import.meta.url);
+	return { query, path: import.meta.url };
 }

package/src/graphql/index.ts

@@ -5,4 +5,10 @@ import GraphQl, {
 	GraphQlRequestOptions,
 } from './GraphQl.js';
 
-export { GraphQl, gql, GraphQlQuery, GraphQlError, type GraphQlRequestOptions };
+export {
+	GraphQl,
+	gql,
+	type GraphQlQuery,
+	GraphQlError,
+	type GraphQlRequestOptions,
+};

package/src/index.ts

@@ -1,21 +1,22 @@
-import { getContext } from 'svelte';
+import { getContext, onDestroy } from 'svelte';
 import type Route from './routing/Route.js';
 import type Router from './routing/Router.js';
 import type SsrCache from './ssr/SsrCache.js';
 import type Site from './routing/Site.js';
 import type GraphQl from './graphql/GraphQl.js';
-import Crelte from './Crelte.js';
-import CrelteRouted from './CrelteRouted.js';
-import CrelteBase from './CrelteBase.js';
-import { Global, GlobalData } from './loadData/Globals.js';
-import { Cookies } from './cookies/index.js';
-import { Readable } from 'crelte-std/stores';
+import Crelte, { type QueryOptions } from './Crelte.js';
+import CrelteRequest from './CrelteRequest.js';
+import type { Global, GlobalData } from './loadData/Globals.js';
+import type { Cookies } from './cookies/index.js';
+import type { Readable } from 'crelte-std/stores';
 
-export { Crelte, CrelteRouted };
-export type { CrelteBase };
+export { Crelte, CrelteRequest, type QueryOptions };
 
 /**
- * Get the Crelte from the current context
+ * Get Crelte from the current context
+ *
+ * ## Note
+ * This only works during component initialisation.
  */
 export function getCrelte(): Crelte {
 	return getContext('crelte');
@@ -23,6 +24,9 @@ export function getCrelte(): Crelte {
 
 /**
  * Get the router from the current context
+ *
+ * ## Note
+ * This only works during component initialisation.
  */
 export function getRouter(): Router {
 	return getCrelte().router;
@@ -30,6 +34,9 @@ export function getRouter(): Router {
 
 /**
  * Get the SSR cache from the current context
+ *
+ * ## Note
+ * This only works during component initialisation.
  */
 export function getSsrCache(): SsrCache {
 	return getCrelte().ssrCache;
@@ -37,56 +44,64 @@ export function getSsrCache(): SsrCache {
 
 /**
  * Get the GraphQl from the current context
+ *
+ * ## Note
+ * This only works during component initialisation.
  */
 export function getGraphQl(): GraphQl {
 	return getCrelte().graphQl;
 }
 
 /**
- * Get the current route
+ * Get a store with the current route
+ *
+ * ## Note
+ * This only works during component initialisation.
  */
 export function getRoute(): Readable<Route> {
 	return getRouter().route;
 }
 
 /**
- * Get the current site
+ * Get a store with the current site
+ *
+ * ## Note
+ * This only works during component initialisation.
  */
 export function getSite(): Readable<Site> {
 	return getRouter().site;
 }
 
 /**
- * Get the next route
- */
-export function getNextRoute(): Readable<Route> {
-	return getRouter().nextRoute;
-}
-
-/**
- * Get the next site
- */
-export function getNextSite(): Readable<Site> {
-	return getRouter().nextSite;
-}
-
-/**
- * returns an env Variables, always needs to be prefixed VITE_
- * Except ENDPOINT_URL and CRAFT_WEB_URL
+ * returns an env variable from the craft/.env file.
+ * All env variables need to start with VITE_
+ * except ENDPOINT_URL and CRAFT_WEB_URL
+ *
+ * ## Note
+ * This only works during component initialisation.
  */
+export function getEnv(name: 'ENDPOINT_URL'): string;
+export function getEnv(name: 'CRAFT_WEB_URL'): string;
+export function getEnv(name: string): string | null;
 export function getEnv(name: string): string | null {
 	return getCrelte().getEnv(name);
 }
 
 /**
  * returns a store which indicates if the a page is loading
+ *
+ * ## Note
+ * This only works during component initialisation.
  */
 export function getLoading(): Readable<boolean> {
 	return getRouter().loading;
 }
 
 /**
- * returns a store which indicates the loading progress
+ * returns a store which indicates the loading progress between 0 and 1
+ *
+ * ## Note
+ * This only works during component initialisation.
  */
 export function getLoadingProgress(): Readable<number> {
 	return getRouter().loadingProgress;
@@ -94,6 +109,9 @@ export function getLoadingProgress(): Readable<number> {
 
 /**
  * returns a store which contains a globalSet
+ *
+ * ## Note
+ * This only works during component initialisation.
  */
 export function getGlobal<T extends GlobalData>(
 	name: string,
@@ -103,7 +121,25 @@ export function getGlobal<T extends GlobalData>(
 
 /**
  * returns the cookies instance
+ *
+ * ## Note
+ * This only works during component initialisation.
  */
 export function getCookies(): Cookies {
 	return getCrelte().cookies;
 }
+
+/**
+ * Listen for requests
+ *
+ * ## Note
+ * This only works during component initialisation.
+ */
+export function onRequest(fn: (cr: CrelteRequest) => void) {
+	const crelte = getCrelte();
+	const rmListener = crelte.router.onRequest((req, site) => {
+		fn(new CrelteRequest(crelte, req, site));
+	});
+
+	onDestroy(rmListener);
+}

package/src/init/client.ts

@@ -1,23 +1,49 @@
 import { CrelteBuilder } from '../Crelte.js';
+import CrelteRequest from '../CrelteRequest.js';
+import { GraphQlQuery } from '../graphql/GraphQl.js';
 import { SiteFromGraphQl } from '../routing/Site.js';
 import { loadFn, pluginsBeforeRender, setupPlugins } from './shared.js';
 import { tick } from 'svelte';
 
+/**
+ * The main function to start the client side rendering
+ */
 export type MainData = {
-	/// svelte app component
+	/** The App.svelte module */
 	app: any;
-	/// error page
+	/** The Error.svelte module */
 	errorPage: any;
-	entryQuery: any;
-	globalQuery?: any;
+	/** The entry query from queries/entry.graphql */
+	entryQuery: GraphQlQuery;
+	/** The global query from queries/global.graphql */
+	globalQuery?: GraphQlQuery;
 
 	// options
+
+	/**
+	 * Preload pages on mouse over
+	 * @default false
+	 */
 	preloadOnMouseOver?: boolean;
+
+	/**
+	 * Use view transitions
+	 * @default false
+	 */
 	viewTransition?: boolean;
+
+	/**
+	 * Play the intro animation
+	 * @default false
+	 */
 	playIntro?: boolean;
 
 	// debug
+
+	/** Enable graphql query debugging */
 	graphQlDebug?: boolean;
+
+	/** Enable request and render timing measurement */
 	debugTiming?: boolean;
 };
 
@@ -31,6 +57,25 @@ const mainDataDefault = {
 	debugTiming: false,
 };
 
+/**
+ * The main function to start the client side rendering
+ *
+ * ## Example
+ * ```
+ * import * as app from './App.svelte';
+ * import * as errorPage from './Error.svelte';
+ * import entryQuery from './queries/entry.graphql';
+ * import globalQuery from './queries/global.graphql';
+ * import { main } from 'crelte/client';
+ *
+ * main({
+ *     app,
+ *     errorPage,
+ *     entryQuery,
+ *     globalQuery,
+ * });
+ * ```
+ */
 export function main(data: MainData) {
 	data = { ...mainDataDefault, ...data };
 
@@ -57,7 +102,7 @@ export function main(data: MainData) {
 		debugTiming: data.debugTiming,
 	});
 
-	// on the client the cookies are always comming from document.cookie
+	// on the client the cookies are always coming from document.cookie
 	builder.setupCookies('');
 
 	const csites = builder.ssrCache.get('crelteSites') as SiteFromGraphQl[];
@@ -86,8 +131,8 @@ export function main(data: MainData) {
 
 	// setup load Data
 
-	crelte.router._internal.onLoad = (route, site, opts) => {
-		const cr = crelte.toRouted(route, site);
+	crelte.router._internal.onLoad = (req, site, opts) => {
+		const cr = new CrelteRequest(crelte, req, site);
 		return loadFn(cr, data.app, data.entryQuery, data.globalQuery, opts);
 	};
 
@@ -111,7 +156,7 @@ export function main(data: MainData) {
 	let firstLoad = true;
 	crelte.router._internal.onLoaded = async (
 		success,
-		route,
+		req,
 		site,
 		readyForProps,
 	) => {
@@ -132,7 +177,7 @@ export function main(data: MainData) {
 			return handleLoadError(readyForProps());
 		}
 
-		const cr = crelte.toRouted(route, site);
+		const cr = new CrelteRequest(crelte, req, site);
 
 		const startTime = data.debugTiming ? Date.now() : null;
 		let render = async () => {
@@ -149,7 +194,7 @@ export function main(data: MainData) {
 				);
 			}
 
-			crelte.router._internal.domReady(route);
+			crelte.router._internal.domReady(cr.req);
 		};
 
 		// render with view Transition if enabled and not in hydration

package/src/init/server.ts

@@ -4,6 +4,8 @@ import { loadFn, pluginsBeforeRender, setupPlugins } from './shared.js';
 import SsrComponents from '../ssr/SsrComponents.js';
 import SsrCache from '../ssr/SsrCache.js';
 import ServerCookies from '../cookies/ServerCookies.js';
+import CrelteRequest from '../CrelteRequest.js';
+import { gql, GraphQlQuery } from '../graphql/GraphQl.js';
 
 export type ServerData = {
 	url: string;
@@ -16,19 +18,49 @@ export type ServerData = {
 	cookies?: string;
 };
 
+/**
+ * The main function to start the server side rendering
+ */
 export type MainData = {
-	/// svelte app component
+	/** The App.svelte module */
 	app: any;
-	entryQuery: any;
-	globalQuery?: any;
+	/** The entry query from queries/entry.graphql */
+	entryQuery: GraphQlQuery;
+	/** The global query from queries/global.graphql */
+	globalQuery?: GraphQlQuery;
 
+	/** Server data provided by crelte-node */
 	serverData: ServerData;
 
 	// debug
+
+	/** Enable graphql query debugging */
 	graphQlDebug?: boolean;
+
+	/** Enable request and render timing measurement */
 	debugTiming?: boolean;
 };
 
+/**
+ * The main function to start the server side rendering
+ *
+ * ## Example
+ * ```
+ * import * as app from './App.svelte';
+ * import entryQuery from './queries/entry.graphql';
+ * import globalQuery from './queries/global.graphql';
+ * import { main } from 'crelte/server';
+ *
+ * export function render(serverData) {
+ *     return main({
+ *         app,
+ *         entryQuery,
+ *         globalQuery,
+ *         serverData,
+ *     });
+ * }
+ * ```
+ */
 export async function main(data: MainData): Promise<{
 	status: number;
 	location?: string;
@@ -64,12 +96,12 @@ export async function main(data: MainData): Promise<{
 
 	// setup load Data
 
-	crelte.router._internal.onLoad = (route, site) => {
-		const cr = crelte.toRouted(route, site);
+	crelte.router._internal.onLoad = (req, site) => {
+		const cr = new CrelteRequest(crelte, req, site);
 		return loadFn(cr, data.app, data.entryQuery, data.globalQuery);
 	};
 
-	const { success, redirect, route, site, props } =
+	const { success, redirect, req, site, props } =
 		await crelte.router._internal.initServer(
 			data.serverData.url,
 			data.serverData.acceptLang,
@@ -79,7 +111,7 @@ export async function main(data: MainData): Promise<{
 	if (redirect) {
 		return {
 			status: 302,
-			location: route.url.toString(),
+			location: req.url.toString(),
 		};
 	}
 
@@ -87,7 +119,7 @@ export async function main(data: MainData): Promise<{
 	const ssrComponents = new SsrComponents();
 	ssrComponents.addToContext(context);
 
-	pluginsBeforeRender(crelte.toRouted(route, site));
+	pluginsBeforeRender(new CrelteRequest(crelte, req, site));
 	crelte.globals._updateSiteId(site.id);
 	// eslint-disable-next-line prefer-const
 	let { html, head } = data.app.default.render(props, { context });
@@ -125,6 +157,23 @@ export type MainErrorData = {
 	serverData: ServerData;
 };
 
+/**
+ * The main function to start the server side rendering
+ * if there was an error
+ *
+ * ## Example
+ * ```
+ * import * as errorPage from './Error.svelte';
+ *
+ * export function renderError(error, serverData) {
+ *     return mainError({
+ *         error,
+ *         errorPage,
+ *         serverData
+ *     });
+ * }
+ * ```
+ */
 export async function mainError(
 	data: MainErrorData,
 ): Promise<{ status: number; html?: string }> {
@@ -164,8 +213,19 @@ async function loadSites(builder: CrelteBuilder): Promise<SiteFromGraphQl[]> {
 		return globalThis['CRAFT_SITES_CACHED'];
 	}
 
-	const resp = (await builder.graphQl.request(
-		'query { crelteSites { id baseUrl language name handle primary } }',
+	const resp = (await builder.graphQl.query(
+		gql`
+			query {
+				crelteSites {
+					id
+					baseUrl
+					language
+					name
+					handle
+					primary
+				}
+			}
+		`,
 		{},
 		// don't cache since we cache ourself
 		{ caching: false },

package/src/init/shared.ts

@@ -1,5 +1,6 @@
-import CrelteRouted, { GraphQlQuery } from '../CrelteRouted.js';
 import Crelte from '../Crelte.js';
+import CrelteRequest from '../CrelteRequest.js';
+import { GraphQlQuery } from '../graphql/GraphQl.js';
 import { LoadData, callLoadData } from '../loadData/index.js';
 import { PluginCreator } from '../plugins/Plugins.js';
 import { LoadOptions } from '../routing/PageLoader.js';
@@ -17,7 +18,7 @@ interface TemplateModule<E, T> {
 	// svelte component
 	default: any;
 
-	loadData?(cr: CrelteRouted, entry: E): Promise<T>;
+	loadData?(cr: CrelteRequest, entry: E): Promise<T>;
 }
 
 type LazyTemplateModule<E, T> =
@@ -31,7 +32,7 @@ export function setupPlugins(crelte: Crelte, plugins: PluginCreator[]) {
 	}
 }
 
-export function pluginsBeforeRender(cr: CrelteRouted): void {
+export function pluginsBeforeRender(cr: CrelteRequest): void {
 	cr.events.trigger('beforeRender', cr);
 }
 
@@ -58,7 +59,7 @@ export function getEntry(page: any): any {
 }
 
 export async function loadFn<D, E, T>(
-	cr: CrelteRouted,
+	cr: CrelteRequest,
 	app: App<D, E, T>,
 	entryQuery: GraphQlQuery,
 	globalQuery?: GraphQlQuery,
@@ -91,14 +92,14 @@ export async function loadFn<D, E, T>(
 	}
 
 	let pageProm = null;
-	if (cr.route.site) {
-		let uri = decodeURI(cr.route.uri);
+	if (cr.req.site) {
+		let uri = decodeURI(cr.req.uri);
 		if (uri.startsWith('/')) uri = uri.substring(1);
 		if (uri === '' || uri === '/') uri = '__home__';
 
 		pageProm = cr.query(entryQuery, {
 			uri,
-			siteId: cr.route.site.id,
+			siteId: cr.req.site.id,
 		});
 	}