kitcn 0.0.1 → 0.12.0

package/dist/validators-B7oIJCAp.js

@@ -0,0 +1,279 @@
+import { asObjectValidator, v } from "convex/values";
+
+//#region src/internal/upstream/index.ts
+/** biome-ignore-all lint: vendored upstream helper source */
+/**
+* Vendored from upstream helper repository at commit c5e52c8.
+* Source path: packages/convex_helpers/index.ts
+*/
+/**
+* asyncMap returns the results of applying an async function over an list.
+*
+* The list can even be a promise, or an iterable like a Set.
+* @param list - Iterable object of items, e.g. an Array, Set, Object.keys
+* @param asyncTransform
+* @returns
+*/
+async function asyncMap(list, asyncTransform) {
+	const promises = [];
+	let index = 0;
+	list = await list;
+	for (const item of list) {
+		promises.push(asyncTransform(item, index));
+		index += 1;
+	}
+	return Promise.all(promises);
+}
+/**
+* pick helps you pick keys from an object more concisely.
+*
+* e.g. `pick({a: v.string(), b: v.number()}, ["a"])` is equivalent to
+* `{a: v.string()}`
+* The alternative could be something like:
+* ```js
+* const obj = { a: v.string(), b: v.number() };
+* // pick does the following
+* const { a } = obj;
+* const onlyA = { a };
+* ```
+*
+* @param obj The object to pick from. Often like { a: v.string() }
+* @param keys The keys to pick from the object.
+* @returns A new object with only the keys you picked and their values.
+*/
+function pick(obj, keys) {
+	return Object.fromEntries(Object.entries(obj).filter(([k]) => keys.includes(k)));
+}
+/**
+* omit helps you omit keys from an object more concisely.
+*
+* e.g. `omit({a: v.string(), b: v.number()}, ["a"])` is equivalent to
+* `{b: v.number()}`
+*
+* The alternative could be something like:
+* ```js
+* const obj = { a: v.string(), b: v.number() };
+* // omit does the following
+* const { a, ...rest } = obj;
+* const withoutA = rest;
+* ```
+*
+* @param obj The object to return a copy of without the specified keys.
+* @param keys The keys to omit from the object.
+* @returns A new object with the keys you omitted removed.
+*/
+function omit(obj, keys) {
+	return Object.fromEntries(Object.entries(obj).filter(([k]) => !keys.includes(k)));
+}
+/**
+* A utility to validate truthiness at runtime, providing a type guard
+*
+* @example
+* ```ts
+* const x: string | null = getValue();
+* assert(x);
+* // x is now of type string
+* ```
+* You can also provide a function, to avoid doing expensive string templating.
+* @param arg A value to assert the truthiness of.
+* @param message An optional message to throw if the value is not truthy, or a function to generate the message.
+*/
+function assert(value, message) {
+	if (!value) throw new Error(typeof message === "function" ? message() : message);
+}
+
+//#endregion
+//#region src/internal/upstream/validators.ts
+function partial(fieldsOrObjOrUnion) {
+	if (fieldsOrObjOrUnion.isConvexValidator) {
+		if (fieldsOrObjOrUnion.kind === "object") return partialVObject(fieldsOrObjOrUnion);
+		if (fieldsOrObjOrUnion.kind === "union") return partialUnion(fieldsOrObjOrUnion);
+		throw new Error("partial only works with union or object Validators, or a Record<string, Validator> currently");
+	}
+	return partialFields(fieldsOrObjOrUnion);
+}
+/**
+* partialFields helps you define an object of optional validators more concisely.
+*
+* e.g. `partialFields({a: v.string(), b: v.number()})` is equivalent to
+* `{a: v.optional(v.string()), b: v.optional(v.number())}`
+*
+* @param obj The object of validators to make optional. e.g. {a: v.string()}
+* @returns A new object of validators that can be the value or undefined.
+*/
+function partialFields(obj) {
+	return Object.fromEntries(Object.entries(obj).map(([k, vv]) => [k, vv.isOptional === "optional" ? vv : v.optional(vv)]));
+}
+/**
+* partialObject helps you define an object of optional validators more concisely.
+*
+* e.g. `partialObject({a: v.string(), b: v.number()})` is equivalent to
+* `{a: v.optional(v.string()), b: v.optional(v.number())}`
+*
+* @param obj The object of validators to make optional. e.g. {a: v.string()}
+* @returns A new object of validators that can be the value or undefined.
+*/
+function partialVObject(obj) {
+	const o = v.object(partialFields(obj.fields));
+	if (obj.isOptional === "optional") return v.optional(o);
+	return o;
+}
+function partialUnion(union) {
+	const u = v.union(...union.members.map((m) => {
+		assert(m.isOptional === "required", "Union members cannot be optional");
+		if (m.kind === "object") return partialVObject(m);
+		if (m.kind === "union") return partialUnion(m);
+		throw new Error(`Invalid union member type: ${m.kind}`);
+	}));
+	if (union.isOptional === "optional") return v.optional(u);
+	return u;
+}
+/** @deprecated Use `v.string()` instead. Any string value. */
+const string = v.string();
+/** @deprecated Use `v.float64()` instead. JavaScript number, represented as a float64 in the database. */
+const number = v.float64();
+/** @deprecated Use `v.float64()` instead. JavaScript number, represented as a float64 in the database. */
+const float64 = v.float64();
+/** @deprecated Use `v.boolean()` instead. boolean value. For typing it only as true, use `l(true)` */
+const boolean = v.boolean();
+/** @deprecated Use `v.int64()` instead. bigint, though stored as an int64 in the database. */
+const biging = v.int64();
+/** @deprecated Use `v.int64()` instead. bigint, though stored as an int64 in the database. */
+const int64 = v.int64();
+/** @deprecated Use `v.any()` instead. Any Convex value */
+const any = v.any();
+/** @deprecated Use `v.null()` instead. Null value. Underscore is so it doesn't shadow the null builtin */
+const null_ = v.null();
+/** @deprecated Use `v.*()` instead. */
+const { id, object, array, bytes, literal, optional, union } = v;
+/** @deprecated Use `v.bytes()` instead. ArrayBuffer validator. */
+const arrayBuffer = v.bytes();
+function addFieldsToValidator(validatorOrFields, fields) {
+	const validator = asObjectValidator(validatorOrFields);
+	if (Object.keys(fields).length === 0) return validator;
+	switch (validator.kind) {
+		case "object": return v.object(intersectValidators(validator.fields, fields));
+		case "union": return v.union(...validator.members.map((m) => addFieldsToValidator(m, fields)));
+		default: throw new Error("Cannot add arguments to a validator that is not an object or union.");
+	}
+}
+function intersectValidators(fields, fields2) {
+	const specificFields = { ...fields };
+	for (const [k, v] of Object.entries(fields2)) {
+		const existing = specificFields[k];
+		if (existing) {
+			if (existing.kind !== v.kind) throw new Error(`Cannot intersect validators with different kinds: ${existing.kind} and ${v.kind}`);
+			if (existing.isOptional !== v.isOptional && existing.isOptional === "optional") specificFields[k] = v;
+		} else specificFields[k] = v;
+	}
+	return specificFields;
+}
+/** Mark fields as deprecated with this permissive validator typed as null */
+const deprecated = v.optional(v.any());
+/** A maximally permissive validator that type checks as a given validator.
+*
+* If you want to have types that match some validator but you have invalid data
+* and you want to temporarily not validate schema for this field,
+* you can use this function to cast the permissive validator.
+*
+* Example in a schema:
+* ```ts
+* export default defineSchema({
+*   myTable: defineTable({
+*    myString: pretend(v.array(v.string())),
+*   }),
+* });
+* //...in some mutation
+* ctx.db.insert("myTable", { myString: 123 as any }); // no runtime error
+* ```
+* Example in function argument validation:
+* ```ts
+* const myQuery = defineQuery({
+*   args: { myNumber: pretend(v.number()) },
+*   handler: async (ctx, args) => {
+*     // args.myNumber is typed as number, but it's not validated.
+*     const num = typeof args.myNumber === "number" ?
+*       args.myNumber : Number(args.myNumber);
+*   },
+* });
+*/
+const pretend = (_typeToImmitate) => v.optional(v.any());
+/** A validator that validates as optional but type checks as required.
+*
+* If you want to assume a field is set for type checking, but your data may not
+* actually have it set for all documents (e.g. when adding a new field),
+* you can use this function to allow the field to be unset at runtime.
+* This is unsafe, but can be convenient in these situations:
+*
+* 1. You are developing locally and want to add a required field and write
+*   code assuming it is set. Once you push the code & schema, you can update
+*   the data to match before running your code.
+* 2. You are going to run a migration right after pushing code, and are ok with
+*   and you don't want to edit your code to handle the field being unset,
+*   your app being in an inconsistent state until the migration completes.
+*
+* This differs from {@link pretend} in that it type checks the inner validator,
+* if the value is provided.
+*
+* Example in a schema:
+* ```ts
+* export default defineSchema({
+*   myTable: defineTable({
+*    myString: pretendRequired(v.array(v.string())),
+*   }),
+* });
+* //...in some mutation
+* ctx.db.insert("myTable", { myString: undefined }); // no runtime error
+* ```
+* Example in function argument validation:
+* ```ts
+* const myQuery = defineQuery({
+*   args: { myNumber: pretendRequired(v.number()) },
+*   handler: async (ctx, args) => {
+*     // args.myNumber is typed as number, but it might be undefined
+*     const num = args.myNumber || 0;
+*   },
+* });
+*/
+const pretendRequired = (optionalType) => v.optional(optionalType);
+/**
+* Converts an optional validator to a required validator.
+*
+* This is the inverse of `v.optional()`. It takes a validator that may be optional
+* and returns the equivalent required validator.
+*
+* ```ts
+* const optionalString = v.optional(v.string());
+* const requiredString = vRequired(optionalString); // v.string()
+*
+* // Already required validators are returned as-is
+* const alreadyRequired = v.string();
+* const stillRequired = vRequired(alreadyRequired); // v.string()
+* ```
+*
+* @param validator The validator to make required.
+* @returns A required version of the validator.
+*/
+function vRequired(validator) {
+	const { kind, isOptional } = validator;
+	if (isOptional === "required") return validator;
+	switch (kind) {
+		case "id": return v.id(validator.tableName);
+		case "string": return v.string();
+		case "float64": return v.float64();
+		case "int64": return v.int64();
+		case "boolean": return v.boolean();
+		case "null": return v.null();
+		case "any": return v.any();
+		case "literal": return v.literal(validator.value);
+		case "bytes": return v.bytes();
+		case "object": return v.object(validator.fields);
+		case "array": return v.array(validator.element);
+		case "record": return v.record(validator.key, validator.value);
+		case "union": return v.union(...validator.members);
+		default: throw new Error("Unknown Convex validator type: " + kind);
+	}
+}
+
+//#endregion
+export { pretendRequired as a, omit as c, pretend as i, pick as l, deprecated as n, vRequired as o, partial as r, asyncMap as s, addFieldsToValidator as t };

package/dist/validators-vzRKjBJC.d.ts

@@ -0,0 +1,88 @@
+import { GenericId, GenericValidator, Infer, ObjectType, OptionalProperty, PropertyValidators, VAny, VArray, VBoolean, VBytes, VFloat64, VId, VInt64, VLiteral, VNull, VObject, VOptional, VRecord, VString, VUnion, Validator, v } from "convex/values";
+import { GenericDataModel, GenericDatabaseReader, SchemaDefinition, TableNamesInDataModel } from "convex/server";
+
+//#region src/internal/upstream/validators.d.ts
+/** Mark fields as deprecated with this permissive validator typed as null */
+declare const deprecated: Validator<null, "optional">;
+/** A maximally permissive validator that type checks as a given validator.
+ *
+ * If you want to have types that match some validator but you have invalid data
+ * and you want to temporarily not validate schema for this field,
+ * you can use this function to cast the permissive validator.
+ *
+ * Example in a schema:
+ * ```ts
+ * export default defineSchema({
+ *   myTable: defineTable({
+ *    myString: pretend(v.array(v.string())),
+ *   }),
+ * });
+ * //...in some mutation
+ * ctx.db.insert("myTable", { myString: 123 as any }); // no runtime error
+ * ```
+ * Example in function argument validation:
+ * ```ts
+ * const myQuery = defineQuery({
+ *   args: { myNumber: pretend(v.number()) },
+ *   handler: async (ctx, args) => {
+ *     // args.myNumber is typed as number, but it's not validated.
+ *     const num = typeof args.myNumber === "number" ?
+ *       args.myNumber : Number(args.myNumber);
+ *   },
+ * });
+ */
+declare const pretend: <T extends GenericValidator>(_typeToImmitate: T) => T;
+/** A validator that validates as optional but type checks as required.
+ *
+ * If you want to assume a field is set for type checking, but your data may not
+ * actually have it set for all documents (e.g. when adding a new field),
+ * you can use this function to allow the field to be unset at runtime.
+ * This is unsafe, but can be convenient in these situations:
+ *
+ * 1. You are developing locally and want to add a required field and write
+ *   code assuming it is set. Once you push the code & schema, you can update
+ *   the data to match before running your code.
+ * 2. You are going to run a migration right after pushing code, and are ok with
+ *   and you don't want to edit your code to handle the field being unset,
+ *   your app being in an inconsistent state until the migration completes.
+ *
+ * This differs from {@link pretend} in that it type checks the inner validator,
+ * if the value is provided.
+ *
+ * Example in a schema:
+ * ```ts
+ * export default defineSchema({
+ *   myTable: defineTable({
+ *    myString: pretendRequired(v.array(v.string())),
+ *   }),
+ * });
+ * //...in some mutation
+ * ctx.db.insert("myTable", { myString: undefined }); // no runtime error
+ * ```
+ * Example in function argument validation:
+ * ```ts
+ * const myQuery = defineQuery({
+ *   args: { myNumber: pretendRequired(v.number()) },
+ *   handler: async (ctx, args) => {
+ *     // args.myNumber is typed as number, but it might be undefined
+ *     const num = args.myNumber || 0;
+ *   },
+ * });
+ */
+declare const pretendRequired: <T extends Validator<any, "required", any>>(optionalType: T) => T;
+type NotUndefined<T> = Exclude<T, undefined>;
+/**
+ * A type that converts an optional validator to a required validator.
+ *
+ * This is the inverse of `VOptional`. It takes a validator that may be optional
+ * and returns the equivalent required validator type.
+ *
+ * @example
+ * ```ts
+ * type OptionalString = VOptional<VString<string, "required">>;
+ * type RequiredString = VRequired<OptionalString>; // VString<string, "required">
+ * ```
+ */
+type VRequired<T extends Validator<any, OptionalProperty, any>> = T extends VId<infer Type, OptionalProperty> ? VId<NotUndefined<Type>, 'required'> : T extends VString<infer Type, OptionalProperty> ? VString<NotUndefined<Type>, 'required'> : T extends VFloat64<infer Type, OptionalProperty> ? VFloat64<NotUndefined<Type>, 'required'> : T extends VInt64<infer Type, OptionalProperty> ? VInt64<NotUndefined<Type>, 'required'> : T extends VBoolean<infer Type, OptionalProperty> ? VBoolean<NotUndefined<Type>, 'required'> : T extends VNull<infer Type, OptionalProperty> ? VNull<NotUndefined<Type>, 'required'> : T extends VAny<infer Type, OptionalProperty> ? VAny<NotUndefined<Type>, 'required'> : T extends VLiteral<infer Type, OptionalProperty> ? VLiteral<NotUndefined<Type>, 'required'> : T extends VBytes<infer Type, OptionalProperty> ? VBytes<NotUndefined<Type>, 'required'> : T extends VObject<infer Type, infer Fields, OptionalProperty, infer FieldPaths> ? VObject<NotUndefined<Type>, Fields, 'required', FieldPaths> : T extends VArray<infer Type, infer Element, OptionalProperty> ? VArray<NotUndefined<Type>, Element, 'required'> : T extends VRecord<infer Type, infer Key, infer Value, OptionalProperty, infer FieldPaths> ? VRecord<NotUndefined<Type>, Key, Value, 'required', FieldPaths> : T extends VUnion<infer Type, infer Members, OptionalProperty, infer FieldPaths> ? VUnion<NotUndefined<Type>, Members, 'required', FieldPaths> : never;
+//#endregion
+export { pretendRequired as i, deprecated as n, pretend as r, VRequired as t };

package/dist/watcher.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import { n as getConvexConfig, r as logger, t as generateMeta } from "./codegen-lF80HSWu.mjs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+//#region src/cli/watcher.ts
+function getWatchRoots(functionsDir) {
+	const convexDir = path.dirname(functionsDir);
+	return [functionsDir, path.join(convexDir, "routers")];
+}
+function parseTrimSegmentsEnv(value) {
+	if (!value) return;
+	const parseFromArray = (segments) => {
+		const normalized = [...new Set(segments.map((segment) => segment.trim()).filter((segment) => segment))];
+		return normalized.length > 0 ? normalized : void 0;
+	};
+	const trimmed = value.trim();
+	if (!trimmed) return;
+	if (trimmed.startsWith("[")) try {
+		const parsed = JSON.parse(trimmed);
+		if (Array.isArray(parsed) && parsed.every((segment) => typeof segment === "string")) return parseFromArray(parsed);
+	} catch {}
+	return parseFromArray(trimmed.split(","));
+}
+function shouldIgnoreWatchPath(watchedPath, functionsDir, outputFile) {
+	const normalizedPath = path.resolve(watchedPath);
+	const normalizedFunctionsDir = path.resolve(functionsDir);
+	const normalizedOutputFile = path.resolve(outputFile);
+	const generatedDir = path.join(normalizedFunctionsDir, "generated");
+	const generatedFile = path.join(normalizedFunctionsDir, "generated.ts");
+	if (normalizedPath === normalizedOutputFile) return true;
+	if (normalizedPath === generatedFile) return true;
+	if (normalizedPath === generatedDir || normalizedPath.startsWith(`${generatedDir}${path.sep}`)) return true;
+	return normalizedPath.endsWith(".runtime.ts");
+}
+async function startWatcher(opts) {
+	const sharedDir = opts?.sharedDir ?? (process.env.KITCN_API_OUTPUT_DIR || void 0);
+	const debug = opts?.debug ?? process.env.KITCN_DEBUG === "1";
+	const scope = opts?.scope ?? process.env.KITCN_CODEGEN_SCOPE ?? "all";
+	const trimSegments = opts?.trimSegments ?? parseTrimSegmentsEnv(process.env.KITCN_CODEGEN_TRIM_SEGMENTS);
+	const debounceMs = opts?.debounceMs ?? 100;
+	const resolveConfig = opts?.getConvexConfig ?? getConvexConfig;
+	const runGenerateMeta = opts?.generateMeta ?? generateMeta;
+	const { functionsDir, outputFile } = resolveConfig(sharedDir);
+	const watchRoots = getWatchRoots(functionsDir);
+	const watch = opts?.watch ?? (await import("chokidar")).watch;
+	let debounceTimer = null;
+	let generateMetaInFlight = false;
+	let generateMetaQueued = false;
+	const createGenerateOptions = () => {
+		const generateOptions = {
+			debug,
+			silent: true,
+			scope
+		};
+		if (trimSegments && trimSegments.length > 0) generateOptions.trimSegments = trimSegments;
+		return generateOptions;
+	};
+	const runGenerateMetaSafely = async () => {
+		if (generateMetaInFlight) {
+			generateMetaQueued = true;
+			return;
+		}
+		generateMetaInFlight = true;
+		try {
+			await runGenerateMeta(sharedDir, createGenerateOptions());
+			logger.success("Convex api updated");
+		} catch (error) {
+			logger.error("Watch codegen error:", error);
+		} finally {
+			generateMetaInFlight = false;
+			if (generateMetaQueued) {
+				generateMetaQueued = false;
+				scheduleGenerateMeta();
+			}
+		}
+	};
+	const scheduleGenerateMeta = () => {
+		if (debounceTimer) clearTimeout(debounceTimer);
+		debounceTimer = setTimeout(() => {
+			debounceTimer = null;
+			runGenerateMetaSafely();
+		}, debounceMs);
+	};
+	return watch(watchRoots, {
+		ignoreInitial: true,
+		ignored: (watchedPath) => shouldIgnoreWatchPath(watchedPath, functionsDir, outputFile)
+	}).on("add", scheduleGenerateMeta).on("change", scheduleGenerateMeta).on("unlink", scheduleGenerateMeta).on("error", (err) => logger.error("Watch error:", err));
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) startWatcher().catch((error) => {
+	logger.error("Watch error:", error);
+	process.exitCode = 1;
+});
+
+//#endregion
+export { getWatchRoots, shouldIgnoreWatchPath, startWatcher };