@liminalfunctions/framework 1.0.0

package/src/code_generation/templates/package.json.mustache

@@ -0,0 +1,18 @@
+{
+    "name": "{{server_name}}-client-library",
+    "version": "1.0.0",
+    "description": "auto-generated client library for {{server_name}}",
+    "license": "ISC",
+    "author": "",
+    "type": "module",
+    "main": "dist/index.js",
+    "scripts": {
+        "build": "tsc"
+    },
+    "dependencies": {
+        "ky": "^1.9.0"
+    },
+    "devDependencies": {
+        "tsx": "^4.19.3"
+    }
+}

package/src/code_generation/templates/tsconfig.json.mustache

@@ -0,0 +1,14 @@
+{
+    "compilerOptions": {
+      "module": "node16",
+      "noImplicitAny": true,
+      "removeComments": true,
+      "preserveConstEnums": true,
+      "outDir": "dist",
+      "sourceMap": true,
+      "declaration": true,
+      //"declarationMap": true//check this
+    },
+    "include": ["src/**/*"],
+    "exclude": []
+  }

package/src/code_generation/templates/types.mustache

@@ -0,0 +1,4 @@
+import { {{type_return}} } from "./{{path_type_return}}.js";
+import { {{type_query}} } from "./{{path_type_query}}.js";
+import { {{type_put}} } from "./{{path_type_put}}.js";
+import { {{type_post}} } from "./{{path_type_post}}.js";

package/src/code_generation/templates/utils.ts.mustache

@@ -0,0 +1,17 @@
+// this is copied directly to ./utils/utils.ts
+
+export function encode_search_params(params: {[key: string]: string | number | boolean | string[]}): {[key: string]: string | number | boolean }{
+    let retval: {[key: string]: string | number | boolean } = {}
+    for(let [key, value] of Object.entries(params)){
+        if(Array.isArray(value)){
+            retval[key] = value.join(',')
+        } else {
+            retval[key] = value;
+        }
+    }
+
+    return retval;
+}
+
+export type Response<Q> = { data: Q }
+export type Response_Multiple<Q> = { data: Q[] }

package/src/code_generation/utils/tab_indent.ts

@@ -0,0 +1,3 @@
+export function indent(count: number, input: string){
+    return '\t'.repeat(count) + input;
+}

package/src/code_generation/utils/type_from_zod.ts

@@ -0,0 +1,140 @@
+import { z, ZodType } from "zod/v4"
+import mongoose, { Schema } from "mongoose";
+import { magic_values } from "../../utils/mongoose_from_zod.js"
+import { indent } from "./tab_indent.js"
+
+/*export function mongoose_from_zod<T>(schema_name: string, zod_definition: z.core.$ZodType) {
+    let mongoose_schema = schema_from_zod(zod_definition);
+    return mongoose.model<T>(schema_name, mongoose_schema);
+}*/
+
+/*export function schema_from_zod(zod_definition: z.core.$ZodType): any {
+    let mongoose_schema = schema_entry_from_zod(zod_definition as z.ZodType);
+    delete mongoose_schema.type.required;
+    delete mongoose_schema.type._id;
+    return mongoose_schema.type;
+}*/
+
+export function type_from_zod(zod_definition: z.ZodType, indent_level: number): string[] {
+    if(!zod_definition._zod) {
+        console.log('ISSUE');
+        console.log(zod_definition);
+    }
+    
+    switch (zod_definition._zod.def.type) {
+        case "string":
+            return ['string'];
+        case "number":
+        case "int":
+            return ['number'];
+        case "object":
+            return parse_object(zod_definition._zod.def as z.core.$ZodObjectDef, indent_level);
+        case "boolean":
+            return ['boolean'];
+        case "date":
+            return ['Date'];
+        case "undefined":
+            return ['undefined']
+        case "null":
+            return ['null']
+        case "array":
+            return parse_array(zod_definition._zod.def as z.core.$ZodArrayDef, indent_level)
+        /*
+        case "any":
+            return ["any"]
+        case "nullable":
+            //stuff is nullable in mongodb by default, so just return the ordinary results of the parse
+            //@ts-expect-error
+            return type_from_zod((zod_definition as z.core.$ZodNullable)._zod.def.innerType)*/
+        case "map":
+            return  parse_map(zod_definition._zod.def as z.core.$ZodMapDef, indent_level);
+        case "enum":
+            return parse_enum(zod_definition._zod.def as z.core.$ZodEnumDef)
+        case "readonly":
+            throw new Error(`Zod type not yet supported by type_from_zod: ${zod_definition._zod.def.type});`)
+        case "default":
+            return type_from_zod((zod_definition._zod.def as z.core.$ZodDefaultDef).innerType as ZodType, indent_level);
+        case "custom":
+            let result = [];
+            if(!magic_values.has(zod_definition)) {
+                throw new Error(`could not find custom parser in the magic value dictionary for type_from_zod`)
+            }
+            let { override_type } = magic_values.get(zod_definition);
+
+            if(override_type === 'mongodb_id'){
+                result = ['string'];
+            } else {
+                throw new Error(`could not find custom parser for ${override_type} in the magic value dictionary`)
+            }
+
+            return result;
+        default:
+            //console.error(zod_definition._zod.def)
+            throw new Error("Cannot process zod type: " + zod_definition._zod.def.type);
+    }
+}
+
+function parse_object(def: z.core.$ZodObjectDef, indent_level: number): string[] {
+    let retval = ['{']
+    for(let [key, value] of Object.entries(def.shape)){
+        //@ts-ignore
+        let key_phrase = (value.safeParse(undefined).success || value._zod.def.type === 'optional') ? `"${key}"?:` : `"${key}":`;
+
+        let non_optional_type = value;
+        
+        //@ts-ignore
+        while(non_optional_type._zod.def.type === 'optional'){ non_optional_type = non_optional_type._zod.def.innerType;}
+        let type_value = type_from_zod(non_optional_type as ZodType, indent_level + 1)
+        
+        if(type_value.length > 1 ){
+            retval.push(indent(indent_level + 1, `${key_phrase} ${type_value[0]}`))
+            retval.push(...type_value.slice(1))
+        } else {
+            retval.push(indent(indent_level + 1, `${key_phrase} ${type_value[0]}`))
+        }
+    }
+
+    retval.push(indent(indent_level, '}'));
+    return retval;
+}
+
+function parse_array(def: z.core.$ZodArrayDef, indent_level: number): any {
+    //@ts-ignore
+    let retval = type_from_zod(def.element as z.ZodType, indent_level + 1)
+    retval[retval.length - 1] = `${retval[retval.length - 1]}[]`
+    return retval;
+}
+
+function parse_enum(def: z.core.$ZodEnumDef): any {
+    return [ `("${Object.values(def.entries).join('" | "')}")`];
+}
+
+function parse_map(def: z.core.$ZodMapDef, indent_level: number): any {
+    let retval = ['{']
+    //@ts-ignore
+    let key_phrase = `[key: ${type_from_zod(def.keyType, indent_level + 1)}]:`;
+
+    //@ts-ignore
+    let type_value = type_from_zod(def.valueType, indent_level + 1)
+    
+    if(type_value.length > 1 ){
+        retval.push(indent(indent_level + 1, `${key_phrase} ${type_value[0]}`))
+        retval.push(...type_value.slice(1))
+    } else {
+        retval.push(indent(indent_level + 1, `${key_phrase} ${type_value[0]}`))
+    }
+
+    retval.push(indent(indent_level, '}'));
+    return retval;
+}
+
+function parse_optional(def: z.core.$ZodOptionalDef): any {
+    //@ts-ignore
+    let type_definition = schema_entry_from_zod(def.innerType);
+    type_definition.required = false;
+    return type_definition;
+}
+
+function parse_mongodb_id(def: z.core.$ZodCustomDef): any {
+    return { type: Schema.Types.ObjectId };
+}

package/src/utils/cache.ts

@@ -0,0 +1,149 @@
+export class Cache<T> {
+    timeout_map: Map<string, NodeJS.Timeout>;
+    base_cache: Map<string, T>;
+    refetch_map: Map<string, Promise<T>>;
+    duration: number;
+
+    constructor(duration: number) {
+        this.timeout_map = new Map<string, NodeJS.Timeout>();
+        this.base_cache = new Map<string, T>();
+        this.refetch_map = new Map<string, Promise<T>>();
+        this.duration = duration;
+    }
+
+    get(key: string): T {
+        this.reset_expiry_timer_for(key);
+        return this.base_cache.get(key);
+    }
+
+    set(key: string, value: T) {
+        this.base_cache.set(key, value);
+        this.reset_expiry_timer_for(key);
+    }
+
+    reset_expiry_timer_for(key: string) {
+        // if the cache already has a timeout for this key,
+        // stop the countdown. We don't want a key that was
+        //recently used getting deleted by an old timeout.
+        if(this.timeout_map.has(key)) {
+            clearTimeout(this.timeout_map.get(key));
+        }
+
+        // add a timeout to the timeout map. When the timeout runs out, it'll remove the key from the cache.
+        // TODO: should I also give the cache a maximum size? It'd be cool if it had the ability to max out
+        // at a certain number of elements and reacted by throwing away the oldest ones. Definitely a premature
+        // optimization, though.
+        if(this.base_cache.has(key)){
+            this.timeout_map.set(key, setTimeout(() => {
+                this.base_cache.delete(key);
+                this.timeout_map.delete(key);
+            }, this.duration));
+        }
+    }
+
+    delete(key: string) {
+        this.base_cache.delete(key);
+        clearTimeout(this.timeout_map.get(key));
+        this.timeout_map.delete(key);
+    }
+
+    async first_get_then_fetch(key: string, fetch_function: () => Promise<T>): Promise<T> {
+        // if we already have the key in the cache, just return it.
+        if (this.base_cache.has(key)) { return this.get(key); }
+
+        // ...otherwise, if we're already fetching the data, wait for
+        // the fetch to finish and return its results.
+        if(this.refetch_map.has(key)){
+            let result_value;
+            try{
+                result_value = await this.refetch_map.get(key);
+            } catch(err){
+                return Promise.reject(err);
+            }
+            return result_value;
+        }
+
+        // ...if we're not already fetching the data,...
+        // ...start to fetch it
+        let result_value;
+        let fetch_promise = fetch_function().finally(() => {
+            this.refetch_map.delete(key);
+        });
+        // ...store the fetch promise in the refetch_map so that any fetch
+        // operations on the same key can use the fetch that's already being
+        // executed instead of starting a new fetch
+        this.refetch_map.set(key, fetch_promise)
+
+        // ...wait for the results,...
+        try {
+            result_value = await fetch_promise;
+        } catch(err){
+            // ...throwing an error if necessary,...
+            return Promise.reject(err);
+        }
+
+        // ...and setting & returning the restults if there's no error.
+        this.set(key, result_value);
+        return result_value;
+    }
+
+    async first_fetch_then_refresh(key: string, fetch_function: () => Promise<T>): Promise<T> {
+        /*console.log('first_fetch_then_refresh')
+        console.log(this.refetch_map.has(key))
+        console.log(this.base_cache.has(key))*/
+
+        // if we're already refetching the value for the key, don't
+        // start refetching the value. It doesn't make sense to refetch
+        // a value we're already fetching. Wait for the existing refetch if necessary.
+        if(this.refetch_map.has(key)){
+            // if we already have the value, we can return anyway.
+            if (this.base_cache.has(key)) { return this.get(key); }
+
+            // otherwise, return whatever is returned by the existing fetch promise.
+            let result_value;
+            try{
+                result_value = await this.refetch_map.get(key);
+            } catch(err){
+                return Promise.reject(err);
+            }
+            return result_value;
+        }
+
+        // if we already have the key, start a fetch promise and return the existing key
+        if (this.base_cache.has(key)) { 
+            let result_value = this.get(key);
+
+            let fetch_promise = fetch_function().finally(() => {
+                this.refetch_map.delete(key);
+            });
+            // ...store the fetch promise in the refetch_map so that any fetch
+            // operations on the same key can use the fetch that's already being
+            // executed instead of starting a new fetch
+            this.refetch_map.set(key, fetch_promise)
+
+            return result_value;
+        }
+
+        // if we don't have the key, generate a fetch promise and return whatever it returns.
+        let retval;
+        let fetch_promise = fetch_function().finally(() => {
+            this.refetch_map.delete(key);
+        });
+        // ...store the fetch promise in the refetch_map so that any fetch
+        // operations on the same key can use the fetch that's already being
+        // executed instead of starting a new fetch
+        this.refetch_map.set(key, fetch_promise)
+
+        // ...wait for the results,...
+        try {
+            retval = await fetch_promise;
+        } catch(err){
+            // ...throwing an error if necessary,...
+            return Promise.reject(err);
+        }
+
+        // ...and setting & returning the restults if there's no error.
+        this.set(key, retval);
+        return retval;
+    }
+}

package/src/utils/mongoose_from_zod.ts

@@ -0,0 +1,191 @@
+import { z } from "zod/v4"
+import mongoose, { Schema } from "mongoose";
+
+export const magic_values = z.registry<{ override_type: string }>();
+
+//export const z_mongodb_id = z.string().length(24).describe('F_Mongodb_ID');
+//export const mongodb_id = () => z_mongodb_id;
+const underlying_mongodb_id_validator = z.string().length(24);
+export const z_mongodb_id = z.custom<string>((val) => {
+    if(!val){ return false; }
+    return underlying_mongodb_id_validator.parse(val) === val;
+}).meta({
+    "type": "string",
+    "format": "string",
+}).register(magic_values, {override_type: 'mongodb_id'});
+//export const z_mongodb_id = underlying_mongodb_id_validator.register(magic_values, {override_type: 'mongodb_id'});
+
+export function mongoose_from_zod<T>(schema_name: string, zod_definition: z.core.$ZodType) {
+    let mongoose_schema = schema_from_zod(zod_definition);
+    return mongoose.model<T>(schema_name, mongoose_schema);
+}
+
+export function schema_from_zod(zod_definition: z.core.$ZodType): any {
+    let mongoose_schema = schema_entry_from_zod(zod_definition as z.ZodType);
+    delete mongoose_schema.type.required;
+    delete mongoose_schema.type._id;
+    return mongoose_schema.type;
+}
+
+export function schema_entry_from_zod(zod_definition: z.ZodType, loop_detector: Set<any> = new Set()): any {
+    if(!zod_definition) {
+        console.error('ISSUE');
+        console.error(zod_definition);
+    }
+
+    let result;
+    switch (zod_definition._zod.def.type) {
+        case "string":
+            result = parse_string(zod_definition._zod.def as z.core.$ZodStringDef);
+            result.required = !zod_definition.safeParse(undefined).success
+            return result;
+        case "number":
+        case "int":
+            result = parse_number(zod_definition._zod.def as z.core.$ZodNumberDef);
+            result.required = !zod_definition.safeParse(undefined).success
+            return result;
+        case "object":
+            result = parse_object(zod_definition._zod.def as z.core.$ZodObjectDef, loop_detector);
+            result.required = !zod_definition.safeParse(undefined).success
+            return result;
+        case "boolean":
+            result = parse_boolean(zod_definition._zod.def as z.core.$ZodBooleanDef);
+            result.required = !zod_definition.safeParse(undefined).success
+            return result;
+        case "date":
+            result = parse_date(zod_definition._zod.def as z.core.$ZodDateDef);
+            result.required = !zod_definition.safeParse(undefined).success
+            return result;
+        case "undefined":
+            throw new Error(`Zod type not yet supported: ${zod_definition._zod.def.type});`)
+        case "null":
+            throw new Error(`Zod type not yet supported: ${zod_definition._zod.def.type});`)
+        case "array" :
+            result = parse_array(zod_definition._zod.def as z.core.$ZodArrayDef, loop_detector);
+            result.required = !zod_definition.safeParse(undefined).success
+            return result;
+        case "nullable":
+            // stuff is nullable in mongodb by default, so just return the ordinary results of the parse
+            //@ts-expect-error
+            return schema_entry_from_zod((zod_definition as z.core.$ZodNullable)._zod.def.innerType, loop_detector)
+        case "optional":
+            return parse_optional(zod_definition._zod.def as z.core.$ZodOptionalDef, loop_detector);
+        case "map":
+            result = parse_map(zod_definition._zod.def as z.core.$ZodMapDef, loop_detector);
+            result.required = !zod_definition.safeParse(undefined).success
+            return result;
+        case "any" :
+            result = { type: Schema.Types.Mixed };
+        case "default":
+            result = parse_default(zod_definition._zod.def as z.core.$ZodDefaultDef, loop_detector);
+            result.required = true;
+            return result;
+        case "enum":
+            result = parse_enum(zod_definition._zod.def as z.core.$ZodEnumDef)
+            result.required = !zod_definition.safeParse(undefined).success
+            return result;
+        case "union":
+            result = parse_union(zod_definition._zod.def as z.core.$ZodUnionDef)
+            result.required = !zod_definition.safeParse(undefined).success
+            return result;
+        case "readonly":
+            throw new Error(`Zod type not yet supported: ${zod_definition._zod.def.type});`)
+        case "custom":
+            if(!magic_values.has(zod_definition)) {
+                throw new Error(`could not find custom parser in the magic value dictionary`)
+            }
+            let { override_type } = magic_values.get(zod_definition);
+
+            if(override_type === 'mongodb_id'){
+                result = parse_mongodb_id(zod_definition._zod.def as z.core.$ZodCustomDef)
+            } else {
+                throw new Error(`could not find custom parser for ${override_type} in the magic value dictionary`)
+            }
+
+            result.required = !zod_definition.safeParse(undefined).success;
+            return result;
+        default:
+            throw new Error("Cannot process zod type: " + zod_definition._zod.def.type);
+    }
+}
+
+function parse_object(def: z.core.$ZodObjectDef, loop_detector: Set<any>): any {
+    if(loop_detector.has(def)) {
+        return {type: Schema.Types.Mixed, required: true}
+    }
+    loop_detector.add(def);
+
+    let retval = {} as any;
+    for(let [key, value] of Object.entries(def.shape)){
+        //@ts-ignore
+        retval[key] = schema_entry_from_zod(value, loop_detector);
+    }
+    return {type: retval, required: true};
+}
+
+function parse_array(def: z.core.$ZodArrayDef, loop_detector: Set<any>): any {
+    //@ts-ignore
+    let retval = { type: [schema_entry_from_zod(def.element, loop_detector)] } as any;
+    retval.required = true;
+    return retval;
+}
+
+function parse_enum(def: z.core.$ZodEnumDef): any {
+    let retval = { type: String } as any;
+    retval.required = true;
+    return retval;
+}
+
+function parse_union(def: z.core.$ZodUnionDef): any {
+    let retval = { type: Schema.Types.Mixed } as any;
+    retval.required = true;
+    return retval;
+}
+
+function parse_map(def: z.core.$ZodMapDef, loop_detector: Set<any>): any {
+    if(def.keyType._zod.def.type !== 'string') { throw new Error('mongoDB only supports maps where the key is a string.'); }
+    //@ts-ignore
+    let retval = { type: Schema.Types.Map, of: schema_entry_from_zod(def.valueType, loop_detector), required: true}
+    retval.required = true;
+    return retval;
+}
+
+function parse_string(def: z.core.$ZodStringDef): any {
+    let retval = { type: String } as any;
+    // for fixing the optional issue
+    // https://github.com/colinhacks/zod/issues/4824
+    return retval;
+}
+
+function parse_number(def: z.core.$ZodNumberDef): any {
+    let retval = { type: Number } as any;
+    return retval;
+}
+
+function parse_boolean(def: z.core.$ZodBooleanDef): any {
+    let retval = { type: Boolean } as any;
+    return retval;
+}
+
+function parse_date(def: z.core.$ZodDateDef): any {
+    let retval = { type: Date } as any;
+    return retval;
+}
+
+function parse_default(def: z.core.$ZodDefaultDef, loop_detector: Set<any>): any {
+    //@ts-ignore
+    let type_definition = schema_entry_from_zod(def.innerType, loop_detector);
+    type_definition.default = def.defaultValue;
+    return type_definition;
+}
+
+function parse_optional(def: z.core.$ZodOptionalDef, loop_detector: Set<any>): any {
+    //@ts-ignore
+    let type_definition = schema_entry_from_zod(def.innerType, loop_detector);
+    type_definition.required = false;
+    return type_definition;
+}
+
+function parse_mongodb_id(def: z.core.$ZodCustomDef): any {
+    return { type: Schema.Types.ObjectId };
+}

package/src/utils/pretty_print_zod.ts

@@ -0,0 +1,75 @@
+import { z } from "zod/v4"
+import { magic_values } from "./mongoose_from_zod.js";
+
+export function pretty_print(zod_definition: z.ZodObject){
+    console.log(parse_object(zod_definition._zod.def, new Set())); 
+}
+
+function parse_any(zod_definition: z.ZodType, loop_detector: Set<any> = new Set()): any {
+    switch (zod_definition._zod.def.type) {
+        case "enum":
+            return parse_enum(zod_definition._zod.def as z.core.$ZodEnumDef);
+        case "string":
+            return 'string';
+        case "number":
+        case "int":
+            return 'number';
+        case "object":
+            return parse_object(zod_definition._zod.def as z.core.$ZodObjectDef, loop_detector);
+        case "boolean":
+            return 'boolean';
+        case "date":
+            return 'date';
+        case "array":
+            return parse_array(zod_definition._zod.def as z.core.$ZodArrayDef, loop_detector)
+        case "union":
+            return parse_union(zod_definition._zod.def as z.core.$ZodUnionDef,)
+        case "custom":
+            if(!magic_values.has(zod_definition)) {
+                throw new Error(`could not find custom parser in the magic value dictionary`)
+            }
+            let { override_type } = magic_values.get(zod_definition);
+
+            if(override_type === 'mongodb_id'){
+                return 'mongodb_id';
+            } else {
+                throw new Error(`could not find custom parser for ${override_type} in the magic value dictionary`)
+            }
+        case "default":
+            //@ts-ignore
+            return parse_any((zod_definition._zod.def as z.core.$ZodDefaultDef).innerType, loop_detector)
+        case "optional":
+            //@ts-ignore
+            return parse_any((zod_definition._zod.def as z.core.$ZodOptionalDef).innerType, loop_detector)
+        default:
+            return `unknown type ${zod_definition._zod.def.type}`
+    }
+}
+
+function parse_array(def: z.core.$ZodArrayDef, loop_detector: Set<any>) {
+    //@ts-ignore
+    return [parse_any(def.element, loop_detector)];
+}
+
+function parse_object(def: z.core.$ZodObjectDef, loop_detector: Set<any>) {
+    if(loop_detector.has(def)) {
+        return 'RECURSION';
+    }
+    loop_detector.add(def);
+
+    let retval = {} as any;
+    for(let [key, value] of Object.entries(def.shape)){
+        //@ts-expect-error
+        retval[key] = parse_any(value, loop_detector);
+    }
+    return retval;
+}
+
+function parse_union(def: z.core.$ZodUnionDef) {
+    //@ts-expect-error
+    return { or: def.options.map(ele => parse_any(ele)) }
+}
+
+function parse_enum(definition: z.core.$ZodEnumDef) {
+    return { enum: definition.entries}
+}