crelte 0.1.0 → 0.1.2

package/src/Crelte.ts

@@ -1,18 +1,12 @@
 import ClientCookies from './cookies/ClientCookies.js';
 import { Cookies } from './cookies/index.js';
 import ServerCookies from './cookies/ServerCookies.js';
-import CrelteBase from './CrelteBase.js';
-import CrelteRouted, { GraphQlQuery } from './CrelteRouted.js';
-import GraphQl, {
-	GraphQlOptions,
-	GraphQlRequestOptions,
-} from './graphql/GraphQl.js';
-import Globals from './loadData/Globals.js';
+import GraphQl, { GraphQlOptions, GraphQlQuery } from './graphql/GraphQl.js';
+import Globals, { Global, GlobalData } from './loadData/Globals.js';
 import Events from './plugins/Events.js';
 import Plugins, { Plugin } from './plugins/Plugins.js';
-import Route from './routing/Route.js';
-import Router, { RouterOpts } from './routing/Router.js';
-import Site, { SiteFromGraphQl } from './routing/Site.js';
+import Router, { RouterOptions } from './routing/Router.js';
+import { SiteFromGraphQl } from './routing/Site.js';
 import SsrCache from './ssr/SsrCache.js';
 
 export class CrelteBuilder {
@@ -39,7 +33,7 @@ export class CrelteBuilder {
 		this.graphQl = new GraphQl(endpoint, this.ssrCache, opts);
 	}
 
-	setupRouter(sites: SiteFromGraphQl[], opts: RouterOpts = {}) {
+	setupRouter(sites: SiteFromGraphQl[], opts: RouterOptions = {}) {
 		this.router = new Router(sites, opts);
 	}
 
@@ -51,80 +45,158 @@ export class CrelteBuilder {
 		return new Crelte(this);
 	}
 }
+/**
+ * Options to configure the request
+ */
+export type QueryOptions = {
+	/**
+	 * Ignore the response status code
+	 * @default false
+	 */
+	ignoreStatusCode?: boolean;
 
-export default class Crelte implements CrelteBase {
-	ssrCache: SsrCache;
-	graphQl: GraphQl;
-	router: Router;
-	plugins: Plugins;
-	events: Events;
-	globals: Globals;
-	cookies: Cookies;
+	/**
+	 * Configure caching
+	 * @default true
+	 */
+	caching?: boolean;
 
-	constructor(builder: CrelteBuilder) {
+	/**
+	 * Status code of the response
+	 * This will be set after the request if
+	 * `ignoreStatusCode` is set to `true`
+	 */
+	status?: number;
+};
+
+/**
+ * This is the main class of Crelte and can be accessed
+ * in component initialisation via `getCrelte()` and is the
+ * first parameter in `loadData`
+ */
+export default class Crelte {
+	protected _ssrCache: SsrCache;
+	protected _graphQl: GraphQl;
+	protected _router: Router;
+	protected _plugins: Plugins;
+	protected _events: Events;
+	protected _globals: Globals;
+	protected _cookies: Cookies;
+
+	constructor(builder: CrelteBuilder | Crelte) {
 		if (!builder.graphQl || !builder.router)
 			throw new Error('builder not ready');
 
-		this.ssrCache = builder.ssrCache;
-		this.graphQl = builder.graphQl;
-		this.router = builder.router;
-		this.plugins = builder.plugins;
-		this.events = builder.events;
-		this.globals = builder.globals;
-		this.cookies = builder.cookies;
+		this._ssrCache = builder.ssrCache;
+		this._graphQl = builder.graphQl;
+		this._router = builder.router;
+		this._plugins = builder.plugins;
+		this._events = builder.events;
+		this._globals = builder.globals;
+		this._cookies = builder.cookies;
+	}
+
+	/**
+	 * Get the SSR cache
+	 */
+	get ssrCache(): SsrCache {
+		return this._ssrCache;
+	}
+
+	/**
+	 * Get the GraphQl instance
+	 */
+	get graphQl(): GraphQl {
+		return this._graphQl;
+	}
+
+	/**
+	 * Get the Router instance
+	 */
+	get router(): Router {
+		return this._router;
+	}
+
+	/**
+	 * Get the Plugins instance
+	 */
+	get plugins(): Plugins {
+		return this._plugins;
+	}
+
+	/**
+	 * Get the Events instance
+	 */
+	get events(): Events {
+		return this._events;
+	}
+
+	/**
+	 * Get the Globals instance
+	 */
+	get globals(): Globals {
+		return this._globals;
+	}
+
+	/**
+	 * Get the Cookies instance
+	 */
+	get cookies(): Cookies {
+		return this._cookies;
 	}
 
+	/**
+	 * Get a Plugin by name
+	 */
 	getPlugin(name: string): Plugin | null {
 		return this.plugins.get(name);
 	}
 
 	/**
-	 * 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
 	 */
+	getEnv(name: 'ENDPOINT_URL'): string;
+	getEnv(name: 'CRAFT_WEB_URL'): string;
+	getEnv(name: string): string | null;
 	getEnv(name: string): string | null {
 		return this.ssrCache.get(name);
 	}
 
-	/// calling this from loadGlobalData will always return null
-	/// this does return the resolved store
-	getGlobal(name: string): any | null {
+	/**
+	 * returns a store which contains a globalSet
+	 *
+	 * ## Note
+	 * This only works in loadData, in loadGlobalData this will
+	 * always return null. In that context you should use
+	 * `CrelteRequest.getGlobalAsync`
+	 */
+	getGlobal<T extends GlobalData>(name: string): Global<T> | null {
 		return this.globals.get(name) ?? null;
 	}
 
-	/// requires a site if the route does not contain a site
-	toRouted(route?: Route, site?: Site): CrelteRouted {
-		if (!route) {
-			route = this.router.route.get();
-		}
-
-		if (!site) {
-			if (!route.site) throw new Error('site is required');
-			site = route.site;
-		}
-
-		return new CrelteRouted(this, route, site);
-	}
-
 	/**
 	 * Run a GraphQl Query
 	 *
-	 * @param query the default export from a graphql file
+	 * @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
-	 * @param options opts `{ caching: true, previewToken: string,
-	 * siteToken: string, ignoreStatusCode: false, headers: {} }`
 	 */
 	async query(
 		query: GraphQlQuery,
 		variables: Record<string, unknown> = {},
-		opts: GraphQlRequestOptions = {},
+		opts: QueryOptions = {},
 	): Promise<unknown> {
 		// this function is added as convenience
-		return this.toRouted().query(query, variables, opts);
+		return this.graphQl.query(query, variables, {
+			route: this.router.route.get(),
+			...opts,
+		});
 	}
 
-	// don't use
+	/** @hidden */
 	_getContext(): Map<string, any> {
 		const map = new Map();
 

package/src/CrelteRequest.ts

@@ -0,0 +1,124 @@
+import Crelte, { QueryOptions } from './Crelte.js';
+import { GraphQlQuery } from './graphql/GraphQl.js';
+import Site from './routing/Site.js';
+import Request from './routing/Request.js';
+import Route from './routing/Route.js';
+import { GlobalData } from './loadData/Globals.js';
+
+export default class CrelteRequest extends Crelte {
+	/**
+	 * The current request
+	 */
+	req: Request;
+
+	/**
+	 * The current site
+	 */
+	site: Site;
+
+	private innerGlobals: Map<string, any>;
+
+	/// requires a site if the route does not contain a site
+	constructor(inner: Crelte, req: Request, site: Site) {
+		super(inner);
+
+		this.req = req;
+		this.site = site;
+		this.innerGlobals = new Map();
+	}
+
+	/**
+	 * Create a CrelteRequest from a Crelte instance
+	 *
+	 * If you don't provide a route or request the current route
+	 * will be used.
+	 *
+	 * ## Note
+	 * If you provide a route it must contain a site or you must
+	 * provide one,
+	 */
+	static fromCrelte(
+		inner: Crelte,
+		req?: Route | Request,
+		site?: Site,
+	): CrelteRequest {
+		if (!req) {
+			req = inner.router.route.get();
+		}
+
+		if (!site) {
+			if (!req.site) throw new Error('site is required');
+			site = req.site;
+		}
+
+		return new CrelteRequest(
+			inner,
+			req instanceof Request ? req : Request.fromRoute(req),
+			site,
+		);
+	}
+
+	/**
+	 * Get the current request
+	 * @deprecated
+	 */
+	get route(): Request {
+		return this.req;
+	}
+
+	/**
+	 * returns a globalSet
+	 *
+	 * ## Note
+	 * This only works in loadData, in loadGlobalData this will
+	 * always return null. In that context you should use
+	 * `.getGlobalAsync`
+	 */
+	getGlobal<T extends GlobalData>(name: string): T | null {
+		return this.innerGlobals.get(name) ?? null;
+	}
+
+	/**
+	 * Get a globalSet and wait until it is loaded
+	 *
+	 * ## Note
+	 * This is only useful in loadGlobalData in all other cases
+	 * you can use `.getGlobal` which does return a Promise
+	 */
+	async getGlobalAsync<T extends GlobalData>(
+		name: string,
+	): Promise<T | null> {
+		const global = this.innerGlobals.get(name);
+		if (global) return global;
+
+		const r = await this.globals.getAsync<T>(name);
+		if (!r) return null;
+
+		return r.bySiteId(this.site.id);
+	}
+
+	/**
+	 * 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: QueryOptions = {},
+	): Promise<unknown> {
+		// this function is added as convenience
+		return this.graphQl.query(query, variables, {
+			route: this.req,
+			...opts,
+		});
+	}
+
+	/** @hidden */
+	_globalDataLoaded() {
+		this.innerGlobals = this.globals._globalsBySite(this.site.id);
+	}
+}

package/src/blocks/Blocks.svelte

@@ -1,22 +1,10 @@
 <script context="module" lang="ts">
-	import { CrelteRouted } from '../index.js';
+	import CrelteRequest from '../CrelteRequest.js';
 
 	/*
 	usage:
 
-	const mods = import.meta.glob('./contentDetail/*.svelte', {
-		// can either be eager loaded or not
-		eager: true,
-	});
-
-	const mods = blockModules(
-		import.meta.glob('./contentDetail/*.svelte', { eager: true }),
-		{
-			alias: {
-				'contentDetail': 'contentDetail',
-			}
-		}
-	);
+	const mods = blockModules(import.meta.glob('./contentDetail/*.svelte'));
 
 	export const loadData = {
 		blocks: (cr, entry) => loadBlocksData(cr, entry.blocks, mods)
@@ -31,14 +19,32 @@
 
 	import Blocks, {
 		type AsyncModule,
-		type Module,
 		type BlockModulesOptions,
 		BlockModules,
 		newBlocks,
 	} from './Blocks.js';
 
-	export type { BlockModules, BlockModulesOptions, AsyncModule, Module };
-
+	/**
+	 * Create a BlockModules instance from modules
+	 *
+	 * ## Example
+	 * ```ts
+	 * const mods = blockModules(
+	 *     import.meta.glob('./contentDetail/*.svelte', { eager: true })
+		);
+	 * ```
+	 *
+	 * ## Example with alias
+	 * ```ts
+	 * const mods = blockModules(
+	 *     import.meta.glob('./contentDetail/*.svelte'),
+	 *     {
+	 *         alias: {
+	 * 		       fakename: 'filename',
+	 *         }
+	 *     }
+	 * );
+	 */
 	export function blockModules(
 		modules: Record<string, AsyncModule>,
 		opts: BlockModulesOptions = {},
@@ -46,8 +52,19 @@
 		return new BlockModules(modules, opts);
 	}
 
+	/**
+	 * Load blocks data
+	 *
+	 * ## Example
+	 * ```ts
+	 * const mods = blockModules(import.meta.glob('./contentDetail/*.svelte'));
+	 *
+	 * export const loadData = {
+	 *     blocks: (cr, entry) => loadBlocksData(cr, entry.blocks, mods)
+	 * };
+	 */
 	export async function loadBlocksData(
-		cr: CrelteRouted,
+		cr: CrelteRequest,
 		blocks: any[],
 		modules: BlockModules,
 	): Promise<Blocks> {

package/src/blocks/Blocks.ts

@@ -1,19 +1,40 @@
-import { CrelteRouted } from '../index.js';
+import { CrelteRequest } from '../index.js';
 import { callLoadData } from '../loadData/index.js';
 
 export interface Module {
-	// svelte component
+	/** Svelte component */
 	default: any;
+
+	/** Handle of the block, this only works with { eager: true } */
 	handle?: string | string[];
+
+	/** If true the typeHandle will be avaiable for this component */
 	keepTypeHandle?: boolean;
 
-	loadData?: (block: any) => Promise<any>;
+	loadData?: (
+		cr: CrelteRequest,
+		block: any,
+		opts: BlockOptions,
+	) => Promise<any>;
 }
 
+export type BlockOptions = {
+	/**
+	 * The returns the sibling block or null if it does not exist
+	 *
+	 * -1 = previous block
+	 * 0 = current block
+	 * 1 = next block
+	 */
+	getSibling: (offset: number) => Record<string, any> | null;
+};
+
 export type AsyncModule = (() => Promise<Module>) | Module;
 
 export type BlockModulesOptions = {
-	// if a block should handle multiple blocks
+	/**
+	 * If a block should handle multiple typehandles
+	 */
 	alias?: Record<string, string>;
 };
 
@@ -81,7 +102,18 @@ export class BlockModules {
 	}
 }
 
-export async function newBlocks(blocks: any[], modules: BlockModules) {
+/**
+ * Creates a new Blocks instance
+ *
+ * Consider using the Blocks component instead
+ *
+ * @param blocks the blocks data each block must have a typeHandle
+ * @param modules the modules created with `blockModules`
+ */
+export async function newBlocks(
+	blocks: any[],
+	modules: BlockModules,
+): Promise<Blocks> {
 	// define all required modules
 	const requiredModules: Set<string> = new Set();
 
@@ -107,7 +139,7 @@ export default class Blocks {
 		this.data = blocks.map(() => null);
 	}
 
-	async loadData(cr: CrelteRouted) {
+	async loadData(cr: CrelteRequest) {
 		this.data = await Promise.all(
 			this.blocks.map((block, i) => {
 				const mod = this.modules.get(block.typeHandle)!;

package/src/blocks/index.ts

@@ -1,14 +1,23 @@
-import Blocks, {
-	type BlockModules,
-	type BlockModulesOptions,
-	type AsyncModule,
-	type Module,
-	blockModules,
-	loadBlocksData,
-} from './Blocks.svelte';
+import Blocks, { blockModules, loadBlocksData } from './Blocks.svelte';
+import type {
+	BlockModules,
+	BlockModulesOptions,
+	AsyncModule,
+	Module,
+	BlockOptions,
+} from './Blocks.js';
+import type BlocksInstance from './Blocks.js';
+import { newBlocks } from './Blocks.js';
 
-export type { BlockModules, BlockModulesOptions, AsyncModule, Module };
+export type {
+	BlocksInstance,
+	BlockModules,
+	BlockModulesOptions,
+	AsyncModule,
+	Module,
+	BlockOptions,
+};
 
-export { Blocks, blockModules, loadBlocksData };
+export { newBlocks, Blocks, blockModules, loadBlocksData };
 
 export default Blocks;

package/src/cookies/ServerCookies.ts

@@ -1,5 +1,5 @@
 import { Cookies, SetOptions } from './index.js';
-import { parseCookies, SetCookie, setCookieToString } from './utils.js';
+import { parseCookies, type SetCookie, setCookieToString } from './utils.js';
 
 export default class ServerCookies implements Cookies {
 	requestCookies: Map<string, string>;

package/src/cookies/index.ts

@@ -14,11 +14,17 @@ export interface Cookies {
 
 	/**
 	 * sets the value of the cookie
+	 *
+	 * ## Note
+	 * in most cases you probably wan't to set the path to '/'
 	 */
 	set(name: string, value: string, opts?: SetOptions): void;
 
+	/**
+	 * removes the cookie
+	 */
 	remove(name: string): void;
 
-	// doc hidden
+	/** @hidden */
 	_init(cookies: string): void;
 }