studiocms 0.2.0 → 0.4.0

package/frontend/utils/build-partial-schema.ts

@@ -1,46 +0,0 @@
-import { Schema } from 'effect';
-
-/**
- * Type guard to check if a schema is of type Schema.Struct with all fields of type Schema.All.
- *
- * @param schema - The schema to check
- * @returns True if the schema is of type Schema.All, false otherwise
- */
-export const isSchemaAll = <T extends Schema.Struct.Fields>(
-	schema: unknown
-): schema is Schema.Struct<T> => {
-	return schema instanceof Schema.Struct;
-};
-
-/**
- * Type helper to create a partial schema type with all fields optional.
- */
-export type PartialSchema<T extends Schema.Struct.Fields> = {
-	[K in keyof T]: T[K] extends Schema.Schema.All ? Schema.optional<T[K]> : never;
-};
-
-/**
- * Builds a partial schema from a given base schema, making all fields optional.
- *
- * @template Fields - The fields of the base schema
- * @param base - The base schema to build the partial schema from
- * @returns A new schema with all fields optional
- */
-export const buildPartialSchema = <const Fields extends Schema.Struct.Fields>(
-	base: Schema.Struct<Fields>
-) => {
-	// Construct a new schema with all fields optional except 'id'
-	const partialFields = Object.entries(base.fields).reduce(
-		(acc, [key, entry]) => {
-			if (isSchemaAll(entry)) {
-				const safeKey = key as keyof Fields;
-				// biome-ignore lint/suspicious/noExplicitAny: cursed magic
-				(acc as any)[safeKey] = Schema.optional(entry);
-			}
-			return acc;
-		},
-		{} as PartialSchema<Fields>
-	);
-
-	return Schema.Struct(partialFields) as Schema.Struct<PartialSchema<Fields>>;
-};

package/frontend/utils/errors.ts

@@ -1,6 +0,0 @@
-import { Data } from 'effect';
-
-export class StudioCMSAPIError extends Data.TaggedError('StudioCMSAPIError')<{
-	message: string;
-	cause?: unknown;
-}> {}

package/frontend/utils/param-extractor.ts

@@ -1,83 +0,0 @@
-import type { APIContext } from 'astro';
-import { Effect, Either, ParseResult, Schema } from 'effect';
-import type { ParseOptions } from 'effect/SchemaAST';
-
-/**
- * Type definition for the parameter extraction function.
- */
-export type ExtractEndpointParams = <T, E>(
-	schema: Schema.Schema<T, E, never>,
-	overrideOptions?: ParseOptions
-) => <EE>(
-	callback: (params: T, ctx: APIContext) => Effect.Effect<Response, EE, never>
-) => (ctx: APIContext) => Effect.Effect<Response, EE, never>;
-
-/**
- * Creates a higher-order function that extracts and validates route parameters from an API context.
- *
- * This utility function takes a schema and optional parse options, returning a function that accepts
- * a callback. The returned function validates the API context parameters against the provided schema
- * and passes the decoded parameters to the callback.
- *
- * @template A - The type of the successfully decoded schema output
- * @template E - The type of the schema encoding/input
- *
- * @param schema - An Effect Schema used to validate and decode the context parameters
- * @param overrideOptions - Optional parse options to customize the schema decoding behavior
- *
- * @returns A function that takes a callback accepting validated parameters and returns another
- * function that processes an APIContext, returning an Effect with a Response
- *
- * @example
- * ```typescript
- * const paramsSchema = Schema.Struct({
- *   id: Schema.String,
- *   page: Schema.Number
- * });
- *
- * const handler = extractParams(paramsSchema)((params) =>
- *   Effect.succeed(new Response(JSON.stringify(params)))
- * );
- * ```
- */
-export const extractParams: ExtractEndpointParams = <T, E>(
-	schema: Schema.Schema<T, E, never>,
-	overrideOptions?: ParseOptions
-) => {
-	// Return a function that takes a callback with the validated parameters
-	return <EE>(callback: (params: T, ctx: APIContext) => Effect.Effect<Response, EE, never>) => {
-		// Return a function that processes the APIContext
-		return (ctx: APIContext): Effect.Effect<Response, EE, never> => {
-			// get user override options or default to empty object
-			const userSchemaOpts = overrideOptions ?? {};
-
-			// merge user options with default error handling options
-			const schemaOpts: ParseOptions = {
-				errors: 'all',
-				...userSchemaOpts,
-			};
-
-			// decode and validate the context parameters using the provided schema and options
-			const data = Schema.decodeUnknownEither(schema, schemaOpts)(ctx.params);
-
-			// If decoding fails, format and return the errors in a Response
-			if (Either.isLeft(data)) {
-				const parsedErrors = ParseResult.ArrayFormatter.formatErrorSync(data.left);
-
-				return Effect.succeed(
-					new Response(
-						JSON.stringify({ error: 'API Parameters Decoding Error', errors: parsedErrors }),
-						{
-							status: 400,
-							statusText: 'Bad Request',
-							headers: { 'Content-Type': 'application/json' },
-						}
-					)
-				);
-			}
-
-			// If decoding is successful, invoke the callback with the validated parameters
-			return callback(data.right, ctx);
-		};
-	};
-};

package/frontend/utils/rest-router.ts

@@ -1,444 +0,0 @@
-import {
-	AllResponse,
-	createEffectAPIRoute,
-	createJsonResponse,
-	genLogger,
-	type HTTPMethod,
-} from '@withstudiocms/effect';
-import type { APIContext, APIRoute } from 'astro';
-import { Effect, type ParseResult, Schema, type SchemaAST } from 'effect';
-import type { NonEmptyReadonlyArray } from 'effect/Array';
-import { StudioCMSAPIError } from './errors.js';
-import { extractParams } from './param-extractor.js';
-
-/**
- * An entry in the route registry defining handlers for a specific ID type.
- *
- * @template IdType - The type of ID used in the routes, either 'number' or 'string'
- *
- * @remarks
- * This type defines a structure for registering API route handlers based on
- * the type of ID used. It includes a mapping for general routes (`__index`)
- * and a function to retrieve handlers for specific IDs.
- *
- * @example
- * ```typescript
- * const userRouteEntry: RegistryEntry<'number'> = {
- *   __idType: 'number',
- *   __index: { GET: async (ctx) => { ... } },
- *   id: (id: number) => ({ GET: async (ctx) => { ... } })
- * };
- * ```
- */
-export type RegistryEntry<IdType extends 'number' | 'string' = 'number'> = {
-	__idType: IdType;
-	__index: Partial<Record<HTTPMethod | 'ALL', APIRoute>>;
-	id?: (
-		id: IdType extends 'number' ? number : string
-	) => Partial<Record<HTTPMethod | 'ALL', APIRoute>>;
-};
-
-/**
- * A union type representing an endpoint route configuration.
- *
- * @remarks
- * This type can either be a `RegistryEntry` configured for numeric IDs
- * or for string IDs, allowing flexibility in defining API endpoint routes.
- *
- * @example
- * ```typescript
- * const numericRoute: EndpointRoute = {
- *   __idType: 'number',
- *   __index: { GET: async (ctx) => { ... } },
- *   id: (id: number) => ({ GET: async (ctx) => { ... } })
- * };
- *
- * const stringRoute: EndpointRoute = {
- *   __idType: 'string',
- *   __index: { GET: async (ctx) => { ... } },
- *   id: (id: string) => ({ GET: async (ctx) => { ... } })
- * };
- * ```
- */
-export type EndpointRoute = RegistryEntry<'number'> | RegistryEntry<'string'>;
-
-/**
- * A registry mapping route types to their corresponding endpoint routes.
- *
- * @remarks
- * This type defines a flexible registry structure where each key represents
- * a route type identifier (string) and maps to an `EndpointRoute` configuration.
- * It allows dynamic registration and lookup of API endpoint routes.
- *
- * @example
- * ```typescript
- * const routes: RouteRegistry = {
- *   'user': userEndpointRoute,
- *   'posts': postsEndpointRoute
- * };
- * ```
- */
-export type RouteRegistry = {
-	[type: string]: EndpointRoute;
-};
-
-/**
- * A function type that defines a sub-page router for REST API endpoints.
- *
- * @param id - The unique identifier for the route or resource
- * @param params - Optional record of string key-value pairs representing route parameters
- * @returns A partial record mapping HTTP methods (or 'ALL' for all methods) to their corresponding API route handlers
- *
- * @example
- * ```typescript
- * const myRouter: SubPageRouter = (id, params) => ({
- *   GET: async (context) => { ... },
- *   POST: async (context) => { ... }
- * });
- * ```
- */
-export type SubPageRouter = (
-	id: string,
-	params?: Record<string, string>
-) => Partial<Record<HTTPMethod | 'ALL', APIRoute>>;
-
-/**
- * A record type mapping sub-path strings to their corresponding sub-page router functions.
- *
- * @remarks
- * This type defines a structure for associating specific sub-paths with their
- * respective router functions, enabling modular handling of REST API endpoints.
- *
- * @example
- * ```typescript
- * const subRouters: SubPathRouter = {
- *   'history': (id) => ({ GET: async (ctx) => { ... } }),
- *   'comments': (id) => ({ POST: async (ctx) => { ... } })
- * };
- * ```
- */
-export type SubPathRouter = Record<string, SubPageRouter>;
-
-const firstLetterUppercase = (str: string) => {
-	return str.charAt(0).toUpperCase() + str.slice(1);
-};
-
-function isNumber(value: unknown): value is number {
-	return typeof value === 'number' && !Number.isNaN(value);
-}
-
-function isString(value: unknown): value is string {
-	return typeof value === 'string';
-}
-
-/**
- * A router function that handles both root paths and sub-paths for REST API endpoints.
- *
- * @param id - The unique identifier for the route or resource, which may include sub-paths
- * @param rootRoute - A function that generates the root route handlers based on the provided ID
- * @param subPathRouter - A record mapping sub-path strings to their corresponding sub-page router functions
- * @returns A partial record mapping HTTP methods (or 'ALL' for all methods) to their corresponding API route handlers
- *
- * @example
- * ```typescript
- * const router = idOrPathRouter(
- *   '123/history/456',
- *   (id) => ({ GET: async (ctx) => { ... } }),
- *   {
- *     'history': (id) => ({ GET: async (ctx) => { ... } }),
- *     'history/[diffid]': (id, params) => ({ GET: async (ctx) => { ... } })
- *   }
- * );
- * ```
- */
-export function idOrPathRouter(
-	id: string,
-	rootRoute: (id: string) => Partial<Record<HTTPMethod | 'ALL', APIRoute>>,
-	subPathRouter: SubPathRouter
-): Partial<Record<HTTPMethod | 'ALL', APIRoute>> {
-	// Handle root path (e.g., /[id])
-	if (!id.includes('/')) {
-		return rootRoute(id);
-	}
-
-	// Handle sub-paths
-	const parts = id.split('/'); // /[id]/subpath/...
-
-	// parse id and subpath
-	const pageId = parts[0];
-	const subPath = parts.slice(1).join('/');
-
-	// Find sub-router (e.g., /[id]/history)
-	const subRouter = subPathRouter[subPath];
-	if (subRouter) {
-		const router = subRouter(pageId);
-		return router;
-	}
-
-	// if no sub-router found, look for sub-paths with parameters (e.g., /[id]/history/[diffid])
-	for (const key in subPathRouter) {
-		if (key.includes('[') && key.includes(']')) {
-			// create a regex to match the pattern
-			const pattern = key.replace(/\[([^\]]+)\]/g, '([^/]+)');
-			const regex = new RegExp(`^${pattern}$`);
-			const match = subPath.match(regex);
-			if (match) {
-				const params: Record<string, string> = {};
-				const paramNames = Array.from(key.matchAll(/\[([^\]]+)\]/g)).map((m) => m[1]);
-				paramNames.forEach((name, index) => {
-					params[name] = match[index + 1];
-				});
-				const router = subPathRouter[key](pageId, params);
-				return router;
-			}
-		}
-	}
-
-	// If no matching sub-router found, return an empty router
-	return {};
-}
-
-/**
- * Processes an API route handler and returns the corresponding response.
- *
- * @param handler - The API route handler function to be executed
- * @param ctx - The API context containing request and other relevant information
- * @param path - The path of the API route being processed
- * @param method - The HTTP method of the request (e.g., GET, POST)
- * @returns An Effect that resolves to a Response object
- *
- * @remarks
- * This function executes the provided API route handler within an Effect context,
- * handling any errors that may occur during execution. If the handler is undefined,
- * it returns an AllResponse. In case of errors, it logs the error and returns a
- * standardized JSON response indicating an internal server error.
- *
- * @example
- * ```typescript
- * const responseEffect = processHandler(myHandler, apiContext, '/my-path', 'GET');
- * ```
- */
-const processHandler = Effect.fn('processHandler')(function* (
-	handler: APIRoute | undefined,
-	ctx: APIContext,
-	path: string,
-	method: string
-): Effect.fn.Return<Response, never, never> {
-	if (!handler) {
-		return AllResponse();
-	}
-
-	const response = yield* Effect.tryPromise({
-		try: async () => await handler(ctx),
-		catch: (error) =>
-			new StudioCMSAPIError({
-				message: `Error in handler for path ${path} [${method}]: ${String(error)}`,
-				cause: error,
-			}),
-	}).pipe(
-		Effect.catchAll((error) =>
-			Effect.logError(`API Route Error: ${String(error)}`).pipe(
-				Effect.as(createJsonResponse({ error: 'Internal Server Error' }, { status: 500 }))
-			)
-		)
-	);
-
-	return response;
-});
-
-/**
- * Creates a REST router that handles HTTP requests based on route type and optional ID parameters.
- *
- * @template Literals - A non-empty readonly array of literal values representing valid route types
- *
- * @param prefix - A prefix string used for logging purposes to identify the route group
- * @param types - A Schema.Literal containing the valid type literals that can be used in the routes
- * @param registry - A RouteRegistry object mapping route types to their handler configurations
- *
- * @returns An Effect API route handler that:
- * - Extracts and validates `type` and `id` parameters from the request
- * - Determines the appropriate handler based on the route type and ID
- * - Supports both numeric and string ID types based on the route configuration
- * - Handles special `__index` routes when no ID is provided
- * - Dispatches requests to the appropriate HTTP method handler (GET, POST, etc.) or ALL handler
- * - Returns appropriate error responses for invalid IDs or missing handlers
- * - Logs errors and returns 500 status for handler execution failures
- *
- * @example
- * ```typescript
- * const router = createRestRouter(
- *   'api',
- *   Schema.Literal('users', 'posts'),
- *   routeRegistry
- * );
- * ```
- */
-export const createRestRouter = <
-	const Literals extends NonEmptyReadonlyArray<SchemaAST.LiteralValue>,
->(
-	prefix: string,
-	types: Schema.Literal<Literals>,
-	registry: RouteRegistry
-) => {
-	const paramSchema = Schema.Struct({
-		type: types,
-		id: Schema.optional(Schema.String),
-	}).annotations({
-		identifier: 'TypeParams',
-		parseIssueTitle: ({ actual }: ParseResult.ParseIssue) => {
-			if (Schema.is(paramSchema)(actual)) {
-				return `Type: ${
-					// biome-ignore lint/style/noNonNullAssertion: we know it's defined here
-					firstLetterUppercase(actual.type!.toString())
-				}`;
-			}
-		},
-	});
-
-	return createEffectAPIRoute(
-		extractParams(paramSchema)(({ type, id = '__index' }, ctx) =>
-			genLogger(`${prefix}:${type}${id !== '__index' ? `:${id}` : ''}:${ctx.request.method}`)(
-				function* () {
-					const method = ctx.request.method.toUpperCase() as keyof Record<
-						HTTPMethod | 'ALL',
-						APIRoute
-					>;
-					const routeGroup = registry[type as string];
-
-					let handlers: Partial<Record<HTTPMethod | 'ALL', APIRoute>> | undefined;
-
-					switch (routeGroup.__idType) {
-						case 'number': {
-							if (id === '__index') {
-								handlers = routeGroup.__index;
-							} else {
-								const numericId = Number(id);
-								if (!isNumber(numericId)) {
-									return createJsonResponse(
-										{ error: `Invalid ID for type ${type}: ${id}` },
-										{ status: 400 }
-									);
-								}
-								handlers = routeGroup.id ? routeGroup.id(numericId) : undefined;
-							}
-							break;
-						}
-						case 'string': {
-							if (id === '__index') {
-								handlers = routeGroup.__index;
-							} else {
-								if (!isString(id)) {
-									return createJsonResponse(
-										{ error: `Invalid ID for type ${type}: ${id}` },
-										{ status: 400 }
-									);
-								}
-								handlers = routeGroup.id ? routeGroup.id(id) : undefined;
-							}
-							break;
-						}
-					}
-
-					const handler = handlers ? handlers[method] || handlers.ALL : undefined;
-
-					return yield* processHandler(handler, ctx, `${type}/${id}`, method);
-				}
-			)
-		)
-	);
-};
-
-/**
- * Creates a simple path-based router for REST API endpoints.
- *
- * @param prefix - A prefix string used for logging purposes to identify the route group
- * @param subPathRouter - A record mapping sub-path strings to their corresponding partial API route handlers
- *
- * @returns An Effect API route handler that:
- * - Extracts and validates the `path` parameter from the request
- * - Determines the appropriate handler based on the specified sub-path
- * - Dispatches requests to the appropriate HTTP method handler (GET, POST, etc.) or ALL handler
- * - Returns an AllResponse if no matching handler is found
- * - Logs errors and returns 500 status for handler execution failures
- *
- * @example
- * ```typescript
- * const router = createSimplePathRouter(
- *   'api',
- *   {
- *     'status': { GET: async (ctx) => { ... } },
- *     'info': { ALL: async (ctx) => { ... } }
- *   }
- * );
- * ```
- */
-export const createSimplePathRouter = (
-	prefix: string,
-	router: Record<string, Partial<Record<HTTPMethod | 'ALL', APIRoute>>>
-) => {
-	const pathSchema = Schema.Struct({
-		path: Schema.transform(Schema.UndefinedOr(Schema.String), Schema.String, {
-			strict: true,
-			decode: (value) => (value === undefined || value === '' ? '__index' : value),
-			encode: (value) => value,
-		}),
-	}).annotations({
-		identifier: 'PathParams',
-		parseIssueTitle: ({ actual }: ParseResult.ParseIssue) => {
-			if (Schema.is(pathSchema)(actual)) {
-				return `Path: ${firstLetterUppercase(actual.path?.toString() || 'index')}`;
-			}
-		},
-	});
-
-	return createEffectAPIRoute(
-		extractParams(pathSchema)(({ path }, ctx) =>
-			genLogger(`${prefix}:${path}:${ctx.request.method}`)(function* () {
-				const method = ctx.request.method.toUpperCase() as keyof Record<
-					HTTPMethod | 'ALL',
-					APIRoute
-				>;
-
-				const handlers = router[path];
-
-				if (!handlers) {
-					return AllResponse();
-				}
-
-				const handler = handlers[method] || handlers.ALL;
-
-				return yield* processHandler(handler, ctx, path, method);
-			})
-		)
-	);
-};
-
-/**
- * Retrieves the router handlers for a specific ID from a sub-path router.
- *
- * @param id - The unique identifier for the route or resource
- * @param subPathRouter - A record mapping sub-path strings to their corresponding sub-page router functions
- * @returns A partial record mapping HTTP methods (or 'ALL' for all methods) to their corresponding API route handlers
- *
- * @example
- * ```typescript
-
- * const handlers = pathRouter(
- *   '123',
- *   {
- *     'history': (id) => ({ GET: async (ctx) => { ... } }),
- *     'comments': (id) => ({ POST: async (ctx) => { ... } })
- *   }
- * );
- * ```
- */
-export function pathRouter(
-	id: string,
-	subPathRouter: SubPathRouter
-): Partial<Record<HTTPMethod | 'ALL', APIRoute>> {
-	// Look for sub-router (e.g., /history)
-	if (!subPathRouter[id]) return {};
-
-	// Return the router for the specified ID
-	return subPathRouter[id](id);
-}