docs: finish initial typedoc setup, add contribute notes, jsdocs

Author: JulianCataldo

.eslintignore

@@ -9,3 +9,5 @@ dist
 .old*
 
 labs
+
+/index.ts

CONTRIBUTING.md

@@ -56,3 +56,45 @@ That way, you'll be able to use them with your locally developed Gracile version
 nodemon -w 'node_modules/@gracile' -x 'vite dev'
 
 -->
+
+## Testing
+
+The `./local-ci.sh` can be used locally to simulate the GitHub CI pipeline.  
+No git hooks with Lint-Staged on this repo! It slows down things too much,
+so instead you'll have to remember to launch this local pipeline before
+the ultimate merge.  
+Intermediate commits on a PR that fails a CI is OK. CI passing is only required
+before merging the `fix|feat` branch to the `next` integration branch.
+
+Gracile is still in a sub `<1.x` version, with many breaking changes all over.
+As creating tests for fast moving targets is a waste of time,
+coverage is kept empiric; and added to stabilize APIs that are mostly settled and
+are **user-facing** (e.g. `defineRoute`).
+
+### Integration
+
+Most of the testing is achieved here for now, because it offers the most bang for the buck
+for the end user,
+but it is slower than unit tests, and not optimized well enough yet.  
+The main reason is due to spinning up real Vite dev/build instances that provoke file system/network conflicts (HMR, server…).  
+Workaround: **tests are sequential**, but they could be re-instated to parallel or semi-parallel runs.
+
+The main technique used for Gracile integration tests is snapshots comparison of server-produced responses.  
+Correctness of user-facing package exports is also covered.
+
+### Unit
+
+Most critical aspects of the framework are meant to be unit-tested, with
+priority to the core, for now.
+
+### End-to-end
+
+Head over to the [starter projects](https://github.com/gracile-web/starter-projects)
+where you can find Playwright test suites for each template in build and dev modes.
+
+They simulate route navigation, compare screenshots to be sure that nothing broke,
+and more advanced interactions, notably with client/server communication.
+
+## More
+
+- [Conventional commits](https://www.conventionalcommits.org/en/v1.0.0/)

index.ts

@@ -0,0 +1 @@
+// Makes Typedoc happy

packages/engine/src/plugin.ts

@@ -14,9 +14,29 @@ import { nodeAdapter } from './server/adapters/node.js';
 import type { GracileConfig } from './user-config.js';
 import { buildRoutes } from './vite/plugins/build-routes.js';
 import { virtualRoutes } from './vite/plugins/virtual-routes.js';
+
 export type { GracileConfig };
 
 let isClientBuilt = false;
+
+/**
+ * The main Vite plugin for loading the Gracile framework.
+ *
+ * @param config - Gracile configuration.
+ * @returns Vite plugins. `any` is used to prevent Vite typings version mismatches for the plugin API.
+ * @example
+ * `/vite.config.js`
+ * ```js
+ * import { gracile } from '@gracile/gracile/plugin';
+ * import { defineConfig } from 'vite';
+ *
+ * export default defineConfig({
+ * 	plugins: [
+ * 		gracile({ output: 'server' }),
+ * 	],
+ * });
+ * ```
+ */
 // Return as `any` to avoid Plugin type mismatches when there are multiple Vite versions installed
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export const gracile = (config?: GracileConfig): any /* Plugin */[] => {

packages/engine/src/server/adapters/hono.ts

@@ -13,6 +13,25 @@ export type GracileHonoHandler = (context: {
 	var: unknown;
 }) => Promise<Response>;
 
+/**
+ * @param handler - Takes a pre-built Gracile handler from `./dist/server/entrypoint.js`.
+ * @example
+ * `/src/server.js`
+ * ```js
+ * import { Hono } from 'hono';
+ * import { serve } from '@hono/node-server';
+ *
+ * import * as gracile from '@gracile/gracile/hono';
+ *
+ * import { handler } from './dist/server/entrypoint.js';
+ *
+ * const app = new Hono();
+ *
+ * app.use(gracile.honoAdapter(handler));
+ *
+ * serve(app);
+ * ```
+ */
 export const honoAdapter =
 	(handler: GracileHandler): GracileHonoHandler =>
 	async (context) => {
@@ -30,6 +49,21 @@ export const honoAdapter =
 		throw new Error('Rendering was impossible in the Hono adapter!');
 	};
 
+/**
+ *
+ * @param root - resolve `dist/client` from this file path.
+ * @example
+ * `/src/server.js`
+ * ```js
+ * import * as gracile from '@gracile/gracile/node';
+ * import { Hono } from 'hono';
+ * import { serveStatic } from '@hono/node-server/serve-static';
+ *
+ * const app = new Hono();
+ *
+ * app.get('*', serveStatic({ root: gracile.getClientDistPath(import.meta.url) }));
+ * ```
+ */
 export function getClientDistPath(root: string) {
 	return relative(
 		process.cwd(),

packages/engine/src/server/adapters/node.ts

@@ -27,7 +27,34 @@ function standardResponseInitToNodeResponse(
 	if (responseInit.statusText) res.statusMessage = responseInit.statusText;
 }
 
-export function nodeAdapter(handler: GracileHandler) {
+export type { GracileHandler };
+
+export type GracileNodeHandler = (
+	req: IncomingMessage,
+	res: ServerResponse,
+	locals?: unknown,
+	// eslint-disable-next-line @typescript-eslint/no-invalid-void-type
+) => Promise<ServerResponse<IncomingMessage> | null | void>;
+
+/**
+ * @param handler - Takes a pre-built Gracile handler from `./dist/server/entrypoint.js`.
+ * @example
+ * `/src/server.js`
+ * ```js
+ * import express from 'express';
+ *
+ * import * as gracile from '@gracile/gracile/node';
+ *
+ * import { handler } from './dist/server/entrypoint.js';
+ *
+ * const app = express();
+ *
+ * app.use(gracile.nodeAdapter(handler));
+ *
+ * const server = app.listen();
+ * ```
+ */
+export function nodeAdapter(handler: GracileHandler): GracileNodeHandler {
 	return async function nodeHandler(
 		req: IncomingMessage,
 		res: ServerResponse,
@@ -79,8 +106,21 @@ export function nodeAdapter(handler: GracileHandler) {
 	};
 }
 
+/**
+ * @param root - resolve `dist/client` from this file path.
+ * @example
+ * ```js
+ * `/src/server.js`
+ * import * as gracile from '@gracile/gracile/node';
+ * import express from 'express';
+ *
+ * const app = express();
+ *
+ * app.use(express.static(gracile.getClientDistPath(import.meta.url)));
+ * ```
+ */
 export function getClientDistPath(root: string) {
-	return fileURLToPath(new URL(CLIENT_DIST_DIR, root));
+	return fileURLToPath(new URL(server.CLIENT_DIST_DIR, root));
 }
 
 export { printAddressInfos } from '../utils.js';

packages/engine/src/server/request.ts

@@ -13,14 +13,20 @@ import type * as R from '../routes/route.js';
 
 // type NextFunction = (error?: unknown) => void | Promise<void>;
 
+type StandardResponse = { response: Response; body?: never; init?: never };
+type ResponseWithNodeReadable = {
+	response?: never;
+	body: Readable;
+	init: ResponseInit;
+};
+
+/**
+ * The underlying handler interface that you can use to build your own adapter.
+ */
 export type GracileHandler = (
 	request: Request,
 	locals?: unknown,
-) => Promise<
-	| { response: Response; body?: never; init?: never }
-	| { response?: never; body: Readable; init: ResponseInit }
-	| null
->;
+) => Promise<StandardResponse | ResponseWithNodeReadable | null>;
 
 const CONTENT_TYPE_HTML = { 'Content-Type': 'text/html' };
 

packages/engine/src/server/utils.ts

@@ -12,6 +12,25 @@ import { server as serverConstants } from './constants.js';
 // 	logger.info('HY');
 // });
 
+/**
+ * Pretty print your server instance address as soon as it is listening.
+ * Matches the dev. server CLI output style.
+ *
+ * @param server - Takes an `node:net` `AddressInfo` like object (address, family, port) or just a provided, pre-constructed string.
+ * @example
+ *
+ * ```js
+ * import * as gracile from '@gracile/gracile/hono';
+ * import { serve } from '@hono/node-server';
+ *
+ * // ...
+ *
+ * serve(
+ * 	{ fetch: app.fetch, port: 3030, hostname: 'localhost' },
+ * 	(address) => gracile.printAddressInfos(address),
+ * );
+ * ```
+ */
 export function printAddressInfos(server: string | AddressInfo | null) {
 	let address: null | string = null;
 	if (!server) throw new Error('Incorrect address infos');

packages/engine/src/user-config.ts

@@ -1,16 +1,64 @@
 import type { Connect } from 'vite';
 
+/**
+ * @example
+ * `/vite.config.js`
+ * ```js
+ * import { gracile } from '@gracile/gracile/plugin';
+ * import { defineConfig } from 'vite';
+ *
+ * export default defineConfig({
+ * 	plugins: [
+ * 		gracile({
+ * 			output: 'server',
+ *
+ * 			dev: {
+ * 				locals: (_context) => {
+ * 					return {
+ * 						requestId: crypto.randomUUID(),
+ * 						userEmail: 'admin@admin.home.arpa',
+ * 					};
+ * 				},
+ * 			},
+ *
+ *			routes: {
+ *				exclude: ['**\/a-defective-route.ts'],
+ *			},
+ * 		}),
+ * 	],
+ * });
+ * ```
+ */
 export interface GracileConfig {
 	/**
+	 * The target output for the build phase.
+	 *
+	 * See the [documentation](https://gracile.js.org/docs/learn/usage/output-modes/).
+	 *
 	 * @defaultValue 'static'
 	 */
 	output?: 'static' | 'server';
 
+	/**
+	 * Settings for the development mode.
+	 */
 	dev?: {
+		/**
+		 * Get incoming request context and apply locals for the Gracile request handler.
+		 * Useful for mocking the production server.
+		 *
+		 * For `server` mode only.
+		 */
 		locals?: (context: { nodeRequest: Connect.IncomingMessage }) => unknown;
 	};
 
+	/**
+	 * Settings for routes in `/src/routes`.
+	 */
 	routes?: {
+		/**
+		 * Exclude routes with an array of patterns. Useful for debugging.
+		 */
 		exclude?: string[];
 	};
 }

packages/engine/typedoc.json

@@ -0,0 +1,12 @@
+{
+  "extends": ["../../typedoc.base.jsonc"],
+  // If not set, will result in a warning being printed since it's likely a misconfiguration
+  "entryPoints": [
+    //
+    "./src/index.ts"
+    // "./src/plugin.ts",
+    // "./src/server-html.ts"
+    // "./src/route.ts",
+    // "./src/document.ts",
+  ]
+}