utils-lab 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 - present, nakita628
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# utils-lab
+
+Schema codegen utilities for Zod, Valibot, ArkType, Effect Schema.
+
+Distributed under the MIT License. See [LICENSE](https://github.com/nakita628/utils-lab?tab=MIT-1-ov-file) for more information.

package/dist/index.d.mts

@@ -0,0 +1,184 @@
+//#region src/helper/makePropertiesGenerator.d.ts
+/**
+ * Create a properties generator for a specific validation library
+ * Combines field filtering, comment cleaning, and code generation
+ * @param libraryPrefix - The library prefix (e.g., 'z', 'v')
+ * @returns A function that generates property definitions
+ */
+declare function makePropertiesGenerator(libraryPrefix: string): (modelFields: readonly {
+  readonly documentation: string;
+  readonly modelName: string;
+  readonly fieldName: string;
+  readonly validation: string | null;
+  readonly comment: readonly string[];
+}[], includeComments: boolean) => string;
+//#endregion
+//#region src/utils/index.d.ts
+/**
+ * Capitalize the first character
+ */
+declare function makeCapitalized(str: string): string;
+/**
+ * Convert camelCase/PascalCase to snake_case
+ */
+declare function makeSnakeCase(name: string): string;
+/**
+ * Generate schema variable name
+ */
+declare function makeSchemaVarName(modelName: string): `${string}Schema`;
+/**
+ * Generate relations variable name
+ */
+declare function makeRelationsVarName(modelName: string): `${string}Relations`;
+/**
+ * Generate field reference
+ */
+declare function makeFieldReference(model: string, field: string): `${string}.${string}`;
+/**
+ * Generate export const statement
+ */
+declare function makeExportConst(name: string, value: string): `export const ${string}=${string}`;
+/**
+ * Generate export type statement
+ */
+declare function makeExportType(name: string, value: string): `export type ${string}=${string}`;
+/**
+ * Check if string is a valid model name (PascalCase)
+ */
+declare function isModelName(str: string): str is `${Uppercase<string>}${string}`;
+/**
+ * Check if string is a valid field name (camelCase)
+ */
+declare function isFieldName(str: string): str is `${Lowercase<string>}${string}`;
+/**
+ * Check if string is a valid schema variable name
+ */
+declare function isSchemaVarName(str: string): str is `${Uppercase<string>}${string}Schema`;
+/**
+ * Check if string is a valid relations variable name
+ */
+declare function isRelationsVarName(str: string): str is `${Lowercase<string>}${string}Relations`;
+declare const RELATIONSHIP_SYMBOLS: {
+  readonly 'zero-one': "|o";
+  readonly one: "||";
+  readonly 'zero-many': "}o";
+  readonly many: "}|";
+};
+/**
+ * Generate relationship symbol
+ */
+declare function makeRelationshipSymbol<T extends 'zero-one' | 'one' | 'zero-many' | 'many'>(type: T): (typeof RELATIONSHIP_SYMBOLS)[T];
+/**
+ * Generate Mermaid connector
+ */
+declare function makeMermaidConnector<F extends 'zero-one' | 'one' | 'zero-many' | 'many', T extends 'zero-one' | 'one' | 'zero-many' | 'many'>(from: F, to: T, isOptional?: boolean): `${'|o' | '||' | '}o' | '}|'}${'--' | '..'}${'|o' | '||' | '}o' | '}|'}`;
+/**
+ * Generate relation type
+ */
+declare function makeRelationType<F extends 'zero-one' | 'one' | 'zero-many' | 'many', T extends 'zero-one' | 'one' | 'zero-many' | 'many'>(from: F, to: T): `${F}-to-${T}`;
+/**
+ * Generate parsed relation
+ */
+declare function makeParsedRelation<FM extends string, FF extends string, TM extends string, TF extends string, RT extends `${'zero-one' | 'one' | 'zero-many' | 'many'}-to-${'zero-one' | 'one' | 'zero-many' | 'many'}`>(fromModel: FM, fromField: FF, toModel: TM, toField: TF, type: RT): {
+  readonly from: `${FM}.${FF}`;
+  readonly to: `${TM}.${TF}`;
+  readonly type: RT;
+};
+/**
+ * Check if string is a valid relationship type
+ */
+declare function isRelationshipType(type: string): type is 'zero-one' | 'one' | 'zero-many' | 'many';
+/**
+ * Check if string is a valid relation type
+ */
+declare function isRelationType(type: string): type is `${'zero-one' | 'one' | 'zero-many' | 'many'}-to-${'zero-one' | 'one' | 'zero-many' | 'many'}`;
+/**
+ * Check if string is a valid Mermaid connector
+ */
+declare function isMermaidConnector(str: string): str is `${'|o' | '||' | '}o' | '}|'}${'--' | '..'}${'|o' | '||' | '}o' | '}|'}`;
+/**
+ * Create a document parser that filters out annotation lines
+ */
+declare function makeDocumentParser(annotationPrefix: `@${string}.`): (documentation: string | undefined) => readonly string[];
+/**
+ * Create a validation extractor for a specific annotation prefix
+ */
+declare function makeValidationExtractor(annotationPrefix: `@${string}.`): (documentation: string | undefined) => string | null;
+/**
+ * Create an annotation extractor for a specific prefix
+ */
+declare function makeAnnotationExtractor(annotationPrefix: `@${string}.`): (documentation: string) => string | null;
+/**
+ * Create a JSDoc string from documentation lines
+ */
+declare function makeJsDoc(documentation: string | undefined, excludePrefixes?: readonly `@${string}.`[]): string;
+/**
+ * Create a comment cleaner that removes triple-slash prefixes
+ */
+declare function makeCleanedCommentLines(lines: readonly string[]): readonly string[];
+/**
+ * Create a clean documentation comment from model fields
+ */
+declare function makeCleanDocComment(commentLines: readonly string[], annotationPrefixes?: readonly string[]): string;
+/**
+ * Check if string is a valid annotation prefix
+ */
+declare function isAnnotationPrefix(str: string): str is `@${string}.`;
+/**
+ * Check if documentation contains a specific annotation
+ */
+declare function hasAnnotation(documentation: string | undefined, prefix: `@${string}.`): boolean;
+/**
+ * Create Zod type inference line
+ */
+declare function makeZodInfer(modelName: string): `export type ${string} = z.infer<typeof ${string}Schema>`;
+/**
+ * Create Valibot type inference line
+ */
+declare function makeValibotInfer(modelName: string): `export type ${string} = v.InferInput<typeof ${string}Schema>`;
+/**
+ * Create ArkType type inference line
+ */
+declare function makeArkTypeInfer(modelName: string): `export type ${string} = typeof ${string}Schema.infer`;
+/**
+ * Create Effect Schema type inference line
+ */
+declare function makeEffectSchemaInfer(modelName: string): `export type ${string} = Schema.Schema.Type<typeof ${string}Schema>`;
+/**
+ * Create Zod import statement
+ */
+declare function makeZodImport(variant?: 'v4' | 'mini' | '@hono/zod-openapi'): string;
+/**
+ * Create Valibot import statement
+ */
+declare function makeValibotImport(): string;
+/**
+ * Create ArkType import statement
+ */
+declare function makeArkTypeImport(): string;
+/**
+ * Create Effect Schema import statement
+ */
+declare function makeEffectSchemaImport(): string;
+/**
+ * Create Zod object wrapper
+ */
+declare function makeZodObject(inner: string, wrapperType?: 'object' | 'strictObject' | 'looseObject'): string;
+/**
+ * Create Valibot object wrapper
+ */
+declare function makeValibotObject(inner: string, wrapperType?: 'object' | 'strictObject' | 'looseObject'): string;
+/**
+ * Create Zod cardinality wrapper (array + optional)
+ */
+declare function makeZodCardinality(expr: string, isList: boolean, isRequired: boolean): string;
+/**
+ * Create Valibot cardinality wrapper (array + optional)
+ */
+declare function makeValibotCardinality(expr: string, isList: boolean, isRequired: boolean): string;
+/**
+ * Check if string is a valid object wrapper type
+ */
+declare function isObjectWrapperType(type: string): type is 'object' | 'strictObject' | 'looseObject';
+//#endregion
+export { hasAnnotation, isAnnotationPrefix, isFieldName, isMermaidConnector, isModelName, isObjectWrapperType, isRelationType, isRelationsVarName, isRelationshipType, isSchemaVarName, makeAnnotationExtractor, makeArkTypeImport, makeArkTypeInfer, makeCapitalized, makeCleanDocComment, makeCleanedCommentLines, makeDocumentParser, makeEffectSchemaImport, makeEffectSchemaInfer, makeExportConst, makeExportType, makeFieldReference, makeJsDoc, makeMermaidConnector, makeParsedRelation, makePropertiesGenerator, makeRelationType, makeRelationsVarName, makeRelationshipSymbol, makeSchemaVarName, makeSnakeCase, makeValibotCardinality, makeValibotImport, makeValibotInfer, makeValibotObject, makeValidationExtractor, makeZodCardinality, makeZodImport, makeZodInfer, makeZodObject };

package/dist/index.mjs

@@ -0,0 +1,305 @@
+//#region src/helper/makePropertiesGenerator.ts
+/**
+* Create a properties generator for a specific validation library
+* Combines field filtering, comment cleaning, and code generation
+* @param libraryPrefix - The library prefix (e.g., 'z', 'v')
+* @returns A function that generates property definitions
+*/
+function makePropertiesGenerator(libraryPrefix) {
+	return function generateProperties(modelFields, includeComments) {
+		return modelFields.filter((field) => field.validation).map((field) => {
+			const cleanLines = field.comment.filter((line) => !(line.includes("@relation") || line.includes("@v") || line.includes("@z")));
+			return `${includeComments && cleanLines.length > 0 ? `  /**\n${cleanLines.map((line) => `   * ${line}`).join("\n")}\n   */\n` : ""}  ${field.fieldName}: ${libraryPrefix}.${field.validation}`;
+		}).join(",\n");
+	};
+}
+
+//#endregion
+//#region src/utils/index.ts
+/**
+* Capitalize the first character
+*/
+function makeCapitalized(str) {
+	return `${str.charAt(0).toUpperCase()}${str.slice(1)}`;
+}
+/**
+* Convert camelCase/PascalCase to snake_case
+*/
+function makeSnakeCase(name) {
+	return name.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+}
+/**
+* Generate schema variable name
+*/
+function makeSchemaVarName(modelName) {
+	return `${makeCapitalized(modelName)}Schema`;
+}
+/**
+* Generate relations variable name
+*/
+function makeRelationsVarName(modelName) {
+	return `${modelName.charAt(0).toLowerCase()}${modelName.slice(1)}Relations`;
+}
+/**
+* Generate field reference
+*/
+function makeFieldReference(model, field) {
+	return `${model}.${field}`;
+}
+/**
+* Generate export const statement
+*/
+function makeExportConst(name, value) {
+	return `export const ${name}=${value}`;
+}
+/**
+* Generate export type statement
+*/
+function makeExportType(name, value) {
+	return `export type ${name}=${value}`;
+}
+/**
+* Check if string is a valid model name (PascalCase)
+*/
+function isModelName(str) {
+	return /^[A-Z][a-zA-Z0-9]*$/.test(str);
+}
+/**
+* Check if string is a valid field name (camelCase)
+*/
+function isFieldName(str) {
+	return /^[a-z][a-zA-Z0-9]*$/.test(str);
+}
+/**
+* Check if string is a valid schema variable name
+*/
+function isSchemaVarName(str) {
+	return /^[A-Z][a-zA-Z0-9]*Schema$/.test(str);
+}
+/**
+* Check if string is a valid relations variable name
+*/
+function isRelationsVarName(str) {
+	return /^[a-z][a-zA-Z0-9]*Relations$/.test(str);
+}
+const RELATIONSHIP_SYMBOLS = {
+	"zero-one": "|o",
+	one: "||",
+	"zero-many": "}o",
+	many: "}|"
+};
+const RELATIONSHIP_TYPES = [
+	"zero-one",
+	"one",
+	"zero-many",
+	"many"
+];
+/**
+* Generate relationship symbol
+*/
+function makeRelationshipSymbol(type) {
+	return RELATIONSHIP_SYMBOLS[type];
+}
+/**
+* Generate Mermaid connector
+*/
+function makeMermaidConnector(from, to, isOptional) {
+	const fromSymbol = makeRelationshipSymbol(from);
+	const toSymbol = makeRelationshipSymbol(to);
+	return `${fromSymbol}${isOptional ? ".." : "--"}${toSymbol}`;
+}
+/**
+* Generate relation type
+*/
+function makeRelationType(from, to) {
+	return `${from}-to-${to}`;
+}
+/**
+* Generate parsed relation
+*/
+function makeParsedRelation(fromModel, fromField, toModel, toField, type) {
+	return {
+		from: `${fromModel}.${fromField}`,
+		to: `${toModel}.${toField}`,
+		type
+	};
+}
+/**
+* Check if string is a valid relationship type
+*/
+function isRelationshipType(type) {
+	return RELATIONSHIP_TYPES.includes(type);
+}
+/**
+* Check if string is a valid relation type
+*/
+function isRelationType(type) {
+	const match = type.match(/^(.+)-to-(.+)$/);
+	if (!(match?.[1] && match[2])) return false;
+	return isRelationshipType(match[1]) && isRelationshipType(match[2]);
+}
+/**
+* Check if string is a valid Mermaid connector
+*/
+function isMermaidConnector(str) {
+	return /^(\|o|\|\||\}o|\}\|)(--|\.\.)(\|o|\|\||\}o|\}\|)$/.test(str);
+}
+/**
+* Create a document parser that filters out annotation lines
+*/
+function makeDocumentParser(annotationPrefix) {
+	return function parseDocument(documentation) {
+		return documentation?.split("\n").map((line) => line.trim()).filter((line) => line && !line.includes(annotationPrefix)) ?? [];
+	};
+}
+/**
+* Create a validation extractor for a specific annotation prefix
+*/
+function makeValidationExtractor(annotationPrefix) {
+	const escaped = annotationPrefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	const regex = new RegExp(`${escaped}(.+?)(?:\\n|$)`);
+	return function extractValidation(documentation) {
+		if (!documentation) return null;
+		return documentation.match(regex)?.[1]?.trim() ?? null;
+	};
+}
+/**
+* Create an annotation extractor for a specific prefix
+*/
+function makeAnnotationExtractor(annotationPrefix) {
+	return function extractAnnotation(documentation) {
+		const line = documentation.split("\n").map((s) => s.trim()).find((l) => l.startsWith(annotationPrefix));
+		return line ? line.slice(annotationPrefix.length) : null;
+	};
+}
+/**
+* Create a JSDoc string from documentation lines
+*/
+function makeJsDoc(documentation, excludePrefixes = ["@z.", "@v."]) {
+	const lines = (documentation ?? "").split("\n").map((s) => s.trim()).filter((l) => l && !excludePrefixes.some((prefix) => l.startsWith(prefix)));
+	return lines.length ? `/**\n * ${lines.join("\n * ")}\n */\n` : "";
+}
+/**
+* Create a comment cleaner that removes triple-slash prefixes
+*/
+function makeCleanedCommentLines(lines) {
+	return lines.map((line) => line.replace(/^\/\/\/\s*/, "").trim()).filter(Boolean);
+}
+/**
+* Create a clean documentation comment from model fields
+*/
+function makeCleanDocComment(commentLines, annotationPrefixes = [
+	"@relation",
+	"@v",
+	"@z"
+]) {
+	return commentLines.filter((line) => !annotationPrefixes.some((prefix) => line.includes(prefix))).join("\n").trim();
+}
+/**
+* Check if string is a valid annotation prefix
+*/
+function isAnnotationPrefix(str) {
+	return /^@[a-z]+\.$/.test(str);
+}
+/**
+* Check if documentation contains a specific annotation
+*/
+function hasAnnotation(documentation, prefix) {
+	if (!documentation) return false;
+	return documentation.includes(prefix);
+}
+/**
+* Create Zod type inference line
+*/
+function makeZodInfer(modelName) {
+	return `export type ${modelName} = z.infer<typeof ${modelName}Schema>`;
+}
+/**
+* Create Valibot type inference line
+*/
+function makeValibotInfer(modelName) {
+	return `export type ${modelName} = v.InferInput<typeof ${modelName}Schema>`;
+}
+/**
+* Create ArkType type inference line
+*/
+function makeArkTypeInfer(modelName) {
+	return `export type ${modelName} = typeof ${modelName}Schema.infer`;
+}
+/**
+* Create Effect Schema type inference line
+*/
+function makeEffectSchemaInfer(modelName) {
+	return `export type ${modelName} = Schema.Schema.Type<typeof ${modelName}Schema>`;
+}
+/**
+* Create Zod import statement
+*/
+function makeZodImport(variant) {
+	switch (variant) {
+		case "mini": return `import * as z from 'zod/mini'`;
+		case "@hono/zod-openapi": return `import { z } from '@hono/zod-openapi'`;
+		default: return `import * as z from 'zod'`;
+	}
+}
+/**
+* Create Valibot import statement
+*/
+function makeValibotImport() {
+	return `import * as v from 'valibot'`;
+}
+/**
+* Create ArkType import statement
+*/
+function makeArkTypeImport() {
+	return `import { type } from 'arktype'`;
+}
+/**
+* Create Effect Schema import statement
+*/
+function makeEffectSchemaImport() {
+	return `import { Schema } from 'effect'`;
+}
+/**
+* Create Zod object wrapper
+*/
+function makeZodObject(inner, wrapperType = "object") {
+	switch (wrapperType) {
+		case "strictObject": return `z.strictObject({${inner}})`;
+		case "looseObject": return `z.looseObject({${inner}})`;
+		default: return `z.object({${inner}})`;
+	}
+}
+/**
+* Create Valibot object wrapper
+*/
+function makeValibotObject(inner, wrapperType = "object") {
+	switch (wrapperType) {
+		case "strictObject": return `v.strictObject({${inner}})`;
+		case "looseObject": return `v.looseObject({${inner}})`;
+		default: return `v.object({${inner}})`;
+	}
+}
+/**
+* Create Zod cardinality wrapper (array + optional)
+*/
+function makeZodCardinality(expr, isList, isRequired) {
+	const withList = isList ? `z.array(${expr})` : expr;
+	return isRequired ? withList : `${withList}.optional()`;
+}
+/**
+* Create Valibot cardinality wrapper (array + optional)
+*/
+function makeValibotCardinality(expr, isList, isRequired) {
+	const withList = isList ? `v.array(${expr})` : expr;
+	return isRequired ? withList : `v.optional(${withList})`;
+}
+/**
+* Check if string is a valid object wrapper type
+*/
+function isObjectWrapperType(type) {
+	return type === "object" || type === "strictObject" || type === "looseObject";
+}
+
+//#endregion
+export { hasAnnotation, isAnnotationPrefix, isFieldName, isMermaidConnector, isModelName, isObjectWrapperType, isRelationType, isRelationsVarName, isRelationshipType, isSchemaVarName, makeAnnotationExtractor, makeArkTypeImport, makeArkTypeInfer, makeCapitalized, makeCleanDocComment, makeCleanedCommentLines, makeDocumentParser, makeEffectSchemaImport, makeEffectSchemaInfer, makeExportConst, makeExportType, makeFieldReference, makeJsDoc, makeMermaidConnector, makeParsedRelation, makePropertiesGenerator, makeRelationType, makeRelationsVarName, makeRelationshipSymbol, makeSchemaVarName, makeSnakeCase, makeValibotCardinality, makeValibotImport, makeValibotInfer, makeValibotObject, makeValidationExtractor, makeZodCardinality, makeZodImport, makeZodInfer, makeZodObject };

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "utils-lab",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Utility functions for schema code generation (Zod, Valibot, ArkType, Effect Schema)",
+  "keywords": [
+    "zod",
+    "valibot",
+    "arktype",
+    "effect-schema",
+    "mermaid",
+    "schema",
+    "codegen"
+  ],
+  "license": "MIT",
+  "author": "nakita628",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nakita628/utils-lab"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.mts"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.13",
+    "@types/node": "^25.1.0",
+    "@typescript/native-preview": "7.0.0-dev.20260129.1",
+    "@vitest/coverage-v8": "^4.0.18",
+    "tsdown": "^0.20.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "check": "pnpm biome check --write ./",
+    "typecheck": "tsgo --noEmit",
+    "test": "vitest run",
+    "coverage": "vitest run --coverage",
+    "release": "pnpm build && pnpm publish"
+  }
+}