fossyl 0.1.6 → 0.10.0

package/README.md

@@ -1,101 +1,5 @@
-<div align="center">
-  <img
-    src="https://raw.githubusercontent.com/YoyoSaur/fossyl/main/packages/core/fossyl.svg"
-    alt="Fossyl Logo"
-    width="200"
-  />
+# fossyl
 
-  # Fossyl
+CLI for scaffolding fossyl projects.
 
-  **Type-safe REST API framework designed for AI-assisted development**
-
-  [![npm version](https://badge.fury.io/js/fossyl.svg)](https://www.npmjs.com/package/fossyl)
-  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-</div>
-
-## Overview
-
-Fossyl is a type-safe REST API framework built with TypeScript, specifically designed to work seamlessly with AI-assisted development tools like Claude. It provides inference-heavy APIs with crystal clear error messages, making it easy to build robust REST APIs with full type safety.
-
-## Features
-
-- **Type-Safe Routes**: Full TypeScript type inference for routes, parameters, and responses
-- **REST Semantics Enforcement**: Compile-time validation of REST patterns (e.g., GET can't have body, POST requires body)
-- **Pure Functional Design**: Validator-library agnostic with simple function types
-- **Query Parameter Validation**: Optional type-safe query parameter validation
-- **Authentication Support**: Type-safe authentication with custom authentication functions
-- **AI-First Development**: Designed for seamless integration with AI coding assistants
-
-## Installation
-
-```bash
-npm install fossyl
-# or
-pnpm add fossyl
-# or
-yarn add fossyl
-```
-
-## Quick Start
-
-```typescript
-import { createRouter } from 'fossyl';
-
-// Create a router
-const router = createRouter();
-
-// Define routes with full type safety
-const userRoute = router.endpoint('/users/:id').get({
-  handler: async ({ url }) => {
-    const userId = url.id; // Fully typed!
-    return { id: userId, name: 'John Doe' };
-  }
-});
-
-// Routes with authentication
-const authenticatedRoute = router.endpoint('/protected').get({
-  authenticator: async (headers) => {
-    // Your auth logic here
-    return { userId: headers['user-id'] };
-  },
-  handler: async ({ url }, auth) => {
-    // auth is fully typed based on your authenticator!
-    return { message: `Hello, user ${auth.userId}` };
-  }
-});
-
-// Routes with request body validation
-const createUserRoute = router.endpoint('/users').post({
-  bodyValidator: (data) => {
-    // Your validation logic here
-    return data as { name: string; email: string };
-  },
-  handler: async ({ url, body }) => {
-    // body is fully typed based on your validator!
-    return { id: '123', ...body };
-  }
-});
-
-// Routes with query parameters
-const searchRoute = router.endpoint('/search').get({
-  queryValidator: (data) => {
-    return data as { q: string; limit?: number };
-  },
-  handler: async ({ url, query }) => {
-    // query is fully typed!
-    return { results: [], query: query.q };
-  }
-});
-```
-
-## Documentation
-
-For more detailed documentation, visit the [GitHub repository](https://github.com/YoyoSaur/fossyl).
-
-## Contributing
-
-Contributions are welcome! Please feel free to submit a Pull Request.
-
-## License
-
-MIT License - see the [LICENSE](LICENSE) file for details.
+For AI-assisted development, see [CLAUDE.md](./CLAUDE.md). Full documentation at [github.com/YoyoSaur/fossyl](https://github.com/YoyoSaur/fossyl).

package/bin/fossyl.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/index.mjs');

package/dist/index.d.mts

@@ -1,204 +1,2 @@
-type ExtractUrlParams<Path extends string> = Path extends `${string}/:${infer Param}/${infer Rest}` ? Param | ExtractUrlParams<Rest> : Path extends `${string}/:${infer Param}` ? Param : never;
-type Expand<T> = T extends infer O ? {
-    [K in keyof O]: O[K];
-} : never;
-type Params<Path extends string> = Expand<{
-    [K in ExtractUrlParams<Path>]: string;
-}>;
 
-declare const authBrand: unique symbol;
-type Authentication = {
-    readonly [authBrand]: "Auth";
-};
-declare function authWrapper<T>(auth: T): T & Authentication;
-type RestMethod = "GET" | "POST" | "PUT" | "DELETE";
-type OpenRoute<Path extends string, Method extends RestMethod, Res extends unknown, Query extends unknown | undefined = undefined> = {
-    type: "open";
-    path: Path;
-    method: Method;
-    validator?: never;
-    authenticator?: never;
-    handler: (params: {
-        url: Params<Path>;
-        query: Query;
-    }) => Promise<Res>;
-};
-type AuthenticatedRoute<Path extends string, Method extends RestMethod, Res extends unknown, Auth extends Authentication, Query extends unknown | undefined = undefined> = {
-    type: "authenticated";
-    path: Path;
-    method: Method;
-    validator?: never;
-    authenticator: AuthenticationFunction<Auth>;
-    handler: (params: {
-        url: Params<Path>;
-        query: Query;
-    }, auth: Auth) => Promise<Res>;
-};
-type ValidatedRoute<Path extends string, Method extends RestMethod, Res extends unknown, RequestBody extends unknown, Query extends unknown | undefined = undefined> = {
-    type: "validated";
-    path: Path;
-    method: Method;
-    validator: ValidatorFunction<RequestBody>;
-    authenticator?: never;
-    handler: (params: {
-        url: Params<Path>;
-        query: Query;
-    }, body: RequestBody) => Promise<Res>;
-};
-type FullRoute<Path extends string, Method extends RestMethod, Res extends unknown, RequestBody extends unknown, Auth extends Authentication, Query extends unknown | undefined = undefined> = {
-    type: "full";
-    path: Path;
-    method: Method;
-    validator: ValidatorFunction<RequestBody>;
-    authenticator: AuthenticationFunction<Auth>;
-    handler: Query extends undefined ? (params: {
-        url: Params<Path>;
-    }, auth: Authentication, body: RequestBody) => Promise<Res> : (params: {
-        url: Params<Path>;
-        query: Query;
-    }, auth: Authentication, body: RequestBody) => Promise<Res>;
-};
-
-type ValidatorFunction<T extends unknown = unknown> = (data: unknown) => T;
-type AuthenticationFunction<T extends Authentication> = (headers: Record<string, string>) => T;
-/**
- * This is the most confusing part of the type system, but also key.
- * This type is used to force type inferenece when creating your endpoints.
- * This is the structure to provide `function overload`s. This is so you can have the same function
- * (in our case get,put,post,delete) but allow differnt configurations.
- *
- * These configurations need to be strongly typed force the developers into using the tools.
- *
- * Want to allow Auth? - Gotta pass in authenticator and the type system handles it
- *
- * Also, this is where the core of the Zod system is. We force the body to be a zod validated input.
- * Luckily, this is pretty easy to replace.
- * PART of me wanted to further abstract it such that you needed a translation function but
- * that seemed overengineerd
- *
- */
-/**
- * Configuration type for POST/PUT/DELETE endpoints.
- * These methods require a request body, so they always need a validator.
- *
- * Four variants (with/without auth × with/without query):
- * 1. Validated only, no query: validator + handler(params, body)
- * 2. Validated only, with query: validator + queryValidator + handler(params, body)
- * 3. Full (auth + validated), no query: authenticator + validator + handler(params, auth, body)
- * 4. Full (auth + validated), with query: authenticator + validator + queryValidator + handler(params, auth, body)
- */
-type EndpointCreationFunction<Path extends string, Method extends RestMethod> = {
-    <Res extends unknown, RequestBody extends unknown>(config: {
-        authenticator?: never;
-        validator: ValidatorFunction<RequestBody>;
-        queryValidator?: never;
-        handler: (params: {
-            url: Params<Path>;
-        }, body: RequestBody) => Promise<Res>;
-    }): ValidatedRoute<Path, Method, Res, RequestBody, undefined>;
-    <Res extends unknown, RequestBody extends unknown, Query extends unknown>(config: {
-        authenticator?: never;
-        validator: ValidatorFunction<RequestBody>;
-        queryValidator: ValidatorFunction<Query>;
-        handler: (params: {
-            url: Params<Path>;
-            query: Query;
-        }, body: RequestBody) => Promise<Res>;
-    }): ValidatedRoute<Path, Method, Res, RequestBody, Query>;
-    <Res extends unknown, RequestBody extends unknown, Auth extends Authentication>(config: {
-        authenticator: AuthenticationFunction<Auth>;
-        validator: ValidatorFunction<RequestBody>;
-        queryValidator?: never;
-        handler: (params: {
-            url: Params<Path>;
-        }, auth: Auth, body: RequestBody) => Promise<Res>;
-    }): FullRoute<Path, Method, Res, RequestBody, Auth, undefined>;
-    <Res extends unknown, RequestBody extends unknown, Auth extends Authentication, Query extends unknown>(config: {
-        authenticator: AuthenticationFunction<Auth>;
-        validator: ValidatorFunction<RequestBody>;
-        queryValidator: ValidatorFunction<Query>;
-        handler: (params: {
-            url: Params<Path>;
-            query: Query;
-        }, auth: Auth, body: RequestBody) => Promise<Res>;
-    }): FullRoute<Path, Method, Res, RequestBody, Auth, Query>;
-};
-/**
- * Configuration type for GET/DELETE endpoints.
- * These methods cannot have a request body, so no validator.
- *
- * Four variants (with/without auth × with/without query):
- * 1. Open, no query: just handler(params)
- * 2. Open, with query: queryValidator + handler(params)
- * 3. Authenticated, no query: authenticator + handler(params, auth)
- * 4. Authenticated, with query: authenticator + queryValidator + handler(params, auth)
- */
-type GetEndpointCreationFunction<Path extends string, Method extends RestMethod> = {
-    <Res extends unknown>(config: {
-        authenticator?: never;
-        queryValidator?: never;
-        handler: (params: {
-            url: Params<Path>;
-        }) => Promise<Res>;
-    }): OpenRoute<Path, Method, Res, undefined>;
-    <Res extends unknown, Query extends unknown>(config: {
-        authenticator?: never;
-        queryValidator: ValidatorFunction<Query>;
-        handler: (params: {
-            url: Params<Path>;
-            query: Query;
-        }) => Promise<Res>;
-    }): OpenRoute<Path, Method, Res, Query>;
-    <Res extends unknown, Auth extends Authentication>(config: {
-        authenticator: AuthenticationFunction<Auth>;
-        queryValidator?: never;
-        handler: (params: {
-            url: Params<Path>;
-        }, auth: Auth) => Promise<Res>;
-    }): AuthenticatedRoute<Path, Method, Res, Auth, undefined>;
-    <Res extends unknown, Auth extends Authentication, Query extends unknown>(config: {
-        authenticator: AuthenticationFunction<Auth>;
-        queryValidator: ValidatorFunction<Query>;
-        handler: (params: {
-            url: Params<Path>;
-            query: Query;
-        }, auth: Auth) => Promise<Res>;
-    }): AuthenticatedRoute<Path, Method, Res, Auth, Query>;
-};
-
-type Endpoint<Path extends string> = {
-    get: GetEndpointCreationFunction<Path, "GET">;
-    post: EndpointCreationFunction<Path, "POST">;
-    put: EndpointCreationFunction<Path, "PUT">;
-    delete: GetEndpointCreationFunction<Path, "DELETE">;
-};
-/**
- * Creates a router that ensures all endpoints extend the route.
- * IDK if this is actually useful, but I kinda like it.
- *
- * There def was a part of me that thought about pure generator functions.
- * In fact... they're provided!
- *
- * We can discuss that.
- */
-type Router<BasePath extends string> = {
-    /**
-     * Creates an endpoint
-     * @param path string, must extend Router's string
-     */
-    createEndpoint: <Path extends `${BasePath}${string}`>(path: Path) => Endpoint<Path>;
-    /**
-     * Creates a subrouter
-     * @param path string, must extend Router's string
-     */
-    createSubrouter: <Path extends `${BasePath}${string}`>(path: Path) => Router<Path>;
-};
-
-/**
- * Provides an Ednpoint creater. Would maybe like some other internal stuff? Lowkey... I think we
- * all might just end up using the helper functions of get and del and such.
- * @param _ - this param is still needed because the type is determined at compile time.
- */
-declare function createRouter<BasePath extends string>(_: BasePath): Router<BasePath>;
-
-export { type AuthenticatedRoute, type Authentication, type AuthenticationFunction, type Endpoint, type FullRoute, type OpenRoute, type RestMethod, type Router, type ValidatedRoute, type ValidatorFunction, authWrapper, createRouter };
+export {  }

package/dist/index.d.ts

@@ -1,204 +1,2 @@
-type ExtractUrlParams<Path extends string> = Path extends `${string}/:${infer Param}/${infer Rest}` ? Param | ExtractUrlParams<Rest> : Path extends `${string}/:${infer Param}` ? Param : never;
-type Expand<T> = T extends infer O ? {
-    [K in keyof O]: O[K];
-} : never;
-type Params<Path extends string> = Expand<{
-    [K in ExtractUrlParams<Path>]: string;
-}>;
 
-declare const authBrand: unique symbol;
-type Authentication = {
-    readonly [authBrand]: "Auth";
-};
-declare function authWrapper<T>(auth: T): T & Authentication;
-type RestMethod = "GET" | "POST" | "PUT" | "DELETE";
-type OpenRoute<Path extends string, Method extends RestMethod, Res extends unknown, Query extends unknown | undefined = undefined> = {
-    type: "open";
-    path: Path;
-    method: Method;
-    validator?: never;
-    authenticator?: never;
-    handler: (params: {
-        url: Params<Path>;
-        query: Query;
-    }) => Promise<Res>;
-};
-type AuthenticatedRoute<Path extends string, Method extends RestMethod, Res extends unknown, Auth extends Authentication, Query extends unknown | undefined = undefined> = {
-    type: "authenticated";
-    path: Path;
-    method: Method;
-    validator?: never;
-    authenticator: AuthenticationFunction<Auth>;
-    handler: (params: {
-        url: Params<Path>;
-        query: Query;
-    }, auth: Auth) => Promise<Res>;
-};
-type ValidatedRoute<Path extends string, Method extends RestMethod, Res extends unknown, RequestBody extends unknown, Query extends unknown | undefined = undefined> = {
-    type: "validated";
-    path: Path;
-    method: Method;
-    validator: ValidatorFunction<RequestBody>;
-    authenticator?: never;
-    handler: (params: {
-        url: Params<Path>;
-        query: Query;
-    }, body: RequestBody) => Promise<Res>;
-};
-type FullRoute<Path extends string, Method extends RestMethod, Res extends unknown, RequestBody extends unknown, Auth extends Authentication, Query extends unknown | undefined = undefined> = {
-    type: "full";
-    path: Path;
-    method: Method;
-    validator: ValidatorFunction<RequestBody>;
-    authenticator: AuthenticationFunction<Auth>;
-    handler: Query extends undefined ? (params: {
-        url: Params<Path>;
-    }, auth: Authentication, body: RequestBody) => Promise<Res> : (params: {
-        url: Params<Path>;
-        query: Query;
-    }, auth: Authentication, body: RequestBody) => Promise<Res>;
-};
-
-type ValidatorFunction<T extends unknown = unknown> = (data: unknown) => T;
-type AuthenticationFunction<T extends Authentication> = (headers: Record<string, string>) => T;
-/**
- * This is the most confusing part of the type system, but also key.
- * This type is used to force type inferenece when creating your endpoints.
- * This is the structure to provide `function overload`s. This is so you can have the same function
- * (in our case get,put,post,delete) but allow differnt configurations.
- *
- * These configurations need to be strongly typed force the developers into using the tools.
- *
- * Want to allow Auth? - Gotta pass in authenticator and the type system handles it
- *
- * Also, this is where the core of the Zod system is. We force the body to be a zod validated input.
- * Luckily, this is pretty easy to replace.
- * PART of me wanted to further abstract it such that you needed a translation function but
- * that seemed overengineerd
- *
- */
-/**
- * Configuration type for POST/PUT/DELETE endpoints.
- * These methods require a request body, so they always need a validator.
- *
- * Four variants (with/without auth × with/without query):
- * 1. Validated only, no query: validator + handler(params, body)
- * 2. Validated only, with query: validator + queryValidator + handler(params, body)
- * 3. Full (auth + validated), no query: authenticator + validator + handler(params, auth, body)
- * 4. Full (auth + validated), with query: authenticator + validator + queryValidator + handler(params, auth, body)
- */
-type EndpointCreationFunction<Path extends string, Method extends RestMethod> = {
-    <Res extends unknown, RequestBody extends unknown>(config: {
-        authenticator?: never;
-        validator: ValidatorFunction<RequestBody>;
-        queryValidator?: never;
-        handler: (params: {
-            url: Params<Path>;
-        }, body: RequestBody) => Promise<Res>;
-    }): ValidatedRoute<Path, Method, Res, RequestBody, undefined>;
-    <Res extends unknown, RequestBody extends unknown, Query extends unknown>(config: {
-        authenticator?: never;
-        validator: ValidatorFunction<RequestBody>;
-        queryValidator: ValidatorFunction<Query>;
-        handler: (params: {
-            url: Params<Path>;
-            query: Query;
-        }, body: RequestBody) => Promise<Res>;
-    }): ValidatedRoute<Path, Method, Res, RequestBody, Query>;
-    <Res extends unknown, RequestBody extends unknown, Auth extends Authentication>(config: {
-        authenticator: AuthenticationFunction<Auth>;
-        validator: ValidatorFunction<RequestBody>;
-        queryValidator?: never;
-        handler: (params: {
-            url: Params<Path>;
-        }, auth: Auth, body: RequestBody) => Promise<Res>;
-    }): FullRoute<Path, Method, Res, RequestBody, Auth, undefined>;
-    <Res extends unknown, RequestBody extends unknown, Auth extends Authentication, Query extends unknown>(config: {
-        authenticator: AuthenticationFunction<Auth>;
-        validator: ValidatorFunction<RequestBody>;
-        queryValidator: ValidatorFunction<Query>;
-        handler: (params: {
-            url: Params<Path>;
-            query: Query;
-        }, auth: Auth, body: RequestBody) => Promise<Res>;
-    }): FullRoute<Path, Method, Res, RequestBody, Auth, Query>;
-};
-/**
- * Configuration type for GET/DELETE endpoints.
- * These methods cannot have a request body, so no validator.
- *
- * Four variants (with/without auth × with/without query):
- * 1. Open, no query: just handler(params)
- * 2. Open, with query: queryValidator + handler(params)
- * 3. Authenticated, no query: authenticator + handler(params, auth)
- * 4. Authenticated, with query: authenticator + queryValidator + handler(params, auth)
- */
-type GetEndpointCreationFunction<Path extends string, Method extends RestMethod> = {
-    <Res extends unknown>(config: {
-        authenticator?: never;
-        queryValidator?: never;
-        handler: (params: {
-            url: Params<Path>;
-        }) => Promise<Res>;
-    }): OpenRoute<Path, Method, Res, undefined>;
-    <Res extends unknown, Query extends unknown>(config: {
-        authenticator?: never;
-        queryValidator: ValidatorFunction<Query>;
-        handler: (params: {
-            url: Params<Path>;
-            query: Query;
-        }) => Promise<Res>;
-    }): OpenRoute<Path, Method, Res, Query>;
-    <Res extends unknown, Auth extends Authentication>(config: {
-        authenticator: AuthenticationFunction<Auth>;
-        queryValidator?: never;
-        handler: (params: {
-            url: Params<Path>;
-        }, auth: Auth) => Promise<Res>;
-    }): AuthenticatedRoute<Path, Method, Res, Auth, undefined>;
-    <Res extends unknown, Auth extends Authentication, Query extends unknown>(config: {
-        authenticator: AuthenticationFunction<Auth>;
-        queryValidator: ValidatorFunction<Query>;
-        handler: (params: {
-            url: Params<Path>;
-            query: Query;
-        }, auth: Auth) => Promise<Res>;
-    }): AuthenticatedRoute<Path, Method, Res, Auth, Query>;
-};
-
-type Endpoint<Path extends string> = {
-    get: GetEndpointCreationFunction<Path, "GET">;
-    post: EndpointCreationFunction<Path, "POST">;
-    put: EndpointCreationFunction<Path, "PUT">;
-    delete: GetEndpointCreationFunction<Path, "DELETE">;
-};
-/**
- * Creates a router that ensures all endpoints extend the route.
- * IDK if this is actually useful, but I kinda like it.
- *
- * There def was a part of me that thought about pure generator functions.
- * In fact... they're provided!
- *
- * We can discuss that.
- */
-type Router<BasePath extends string> = {
-    /**
-     * Creates an endpoint
-     * @param path string, must extend Router's string
-     */
-    createEndpoint: <Path extends `${BasePath}${string}`>(path: Path) => Endpoint<Path>;
-    /**
-     * Creates a subrouter
-     * @param path string, must extend Router's string
-     */
-    createSubrouter: <Path extends `${BasePath}${string}`>(path: Path) => Router<Path>;
-};
-
-/**
- * Provides an Ednpoint creater. Would maybe like some other internal stuff? Lowkey... I think we
- * all might just end up using the helper functions of get and del and such.
- * @param _ - this param is still needed because the type is determined at compile time.
- */
-declare function createRouter<BasePath extends string>(_: BasePath): Router<BasePath>;
-
-export { type AuthenticatedRoute, type Authentication, type AuthenticationFunction, type Endpoint, type FullRoute, type OpenRoute, type RestMethod, type Router, type ValidatedRoute, type ValidatorFunction, authWrapper, createRouter };
+export {  }