@f-o-t/config 0.1.0 → 1.0.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FOT (F-O-T)
+
+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

@@ -33,6 +33,8 @@ const config = defineFotConfig({
   external: ["react", "react-dom"],
   typescript: {
     declaration: true,
+    isolatedDeclarations: false,
+    maxMemory: 4096,
   },
   biome: {
     enabled: true,
@@ -61,23 +63,31 @@ The library provides generators to create standard configuration files for your
 
 ```typescript
 import { 
+  defineFotConfig,
   generatePackageJson, 
-  generateTsConfig, 
+  generateTSConfig, 
   generateBiomeConfig 
 } from "@f-o-t/config";
 
-// Generate package.json
-const packageJson = generatePackageJson({
-  name: "@f-o-t/my-library",
-  version: "1.0.0",
-  description: "My FOT library",
+// First, define your configuration
+const config = defineFotConfig({
+  external: ["zod"],
+  plugins: ["operators"],
 });
 
+// Generate package.json
+const packageJson = generatePackageJson(
+  "my-library",  // library name (without @f-o-t/ prefix)
+  "1.0.0",       // version
+  config,        // resolved config
+  { "zod": "^4.3.6" }  // optional custom dependencies
+);
+
 // Generate tsconfig.json
-const tsconfig = generateTsConfig();
+const tsconfig = generateTSConfig(config);
 
 // Generate biome.json
-const biomeConfig = generateBiomeConfig();
+const biomeConfig = generateBiomeConfig(config);
 ```
 
 ## API Reference
@@ -117,7 +127,11 @@ Fully resolved configuration with all defaults applied:
 interface ResolvedFotConfig {
   formats: BuildFormat[];
   external: string[];
-  typescript: Required<TypeScriptOptions>;
+  typescript: {
+    declaration: boolean;
+    isolatedDeclarations: boolean;
+    maxMemory?: number;
+  };
   biome: Required<BiomeOptions>;
   plugins: PluginConfig[];
 }
@@ -133,7 +147,9 @@ type BuildFormat = "esm" | "cjs";
 
 ```typescript
 interface TypeScriptOptions {
-  declaration?: boolean;  // Generate .d.ts files (default: true)
+  declaration?: boolean;          // Generate .d.ts files (default: true)
+  isolatedDeclarations?: boolean; // Use isolated declarations mode for faster, more memory-efficient declaration generation (default: false)
+  maxMemory?: number;             // Maximum memory (in MB) to allocate for TypeScript declaration generation (default: undefined)
 }
 ```
 
@@ -156,24 +172,56 @@ interface PluginConfig {
 
 ## Generators
 
-### `generatePackageJson(options)`
+### `generatePackageJson(libraryName, version, config, customDependencies?)`
 
 Generates a standard package.json configuration for FOT libraries.
 
 **Parameters:**
-- `name`: Package name
+- `libraryName`: Library name (without `@f-o-t/` prefix)
 - `version`: Package version
-- `description`: Package description
-- Additional package.json fields as needed
+- `config`: Resolved FOT configuration (`ResolvedFotConfig`)
+- `customDependencies` (optional): Custom dependencies to include in the package.json
 
-### `generateTsConfig()`
+**Returns:** `PackageJson` object
+
+**Example:**
+```typescript
+const pkg = generatePackageJson(
+  "my-library",
+  "1.0.0",
+  config,
+  { "zod": "^4.3.6" }
+);
+```
+
+### `generateTSConfig(config)`
 
 Generates a standard TypeScript configuration optimized for FOT libraries.
 
-### `generateBiomeConfig()`
+**Parameters:**
+- `config`: Resolved FOT configuration (`ResolvedFotConfig`)
+
+**Returns:** `TSConfig` object
+
+**Example:**
+```typescript
+const tsconfig = generateTSConfig(config);
+```
+
+### `generateBiomeConfig(config)`
 
 Generates a standard Biome configuration for linting and formatting.
 
+**Parameters:**
+- `config`: Resolved FOT configuration (`ResolvedFotConfig`)
+
+**Returns:** `BiomeConfig` object
+
+**Example:**
+```typescript
+const biomeConfig = generateBiomeConfig(config);
+```
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -11,6 +11,18 @@ interface TypeScriptOptions {
 	* @default true
 	*/
 	declaration?: boolean;
+	/**
+	* Use isolated declarations mode for faster, more memory-efficient declaration generation
+	* Requires TypeScript 5.5+
+	* @default false
+	*/
+	isolatedDeclarations?: boolean;
+	/**
+	* Maximum memory (in MB) to allocate for TypeScript declaration generation
+	* Useful for large libraries with complex types
+	* @default undefined (uses Node.js default ~2GB)
+	*/
+	maxMemory?: number;
 }
 /**
 * Biome configuration options
@@ -79,7 +91,11 @@ interface ResolvedFotConfig {
 	/**
 	* TypeScript options
 	*/
-	typescript: Required<TypeScriptOptions>;
+	typescript: {
+		declaration: boolean;
+		isolatedDeclarations: boolean;
+		maxMemory?: number;
+	};
 	/**
 	* Biome options
 	*/
@@ -144,10 +160,13 @@ interface BiomeConfig {
 */
 declare function generateBiomeConfig(config: ResolvedFotConfig): BiomeConfig;
 /**
-* Package.json configuration
+* Package.json configuration.
+* Includes "import" condition so bundlers/Vite can resolve ESM entries
+* under conditions like ["module", "browser", "import"].
 */
 interface PackageExport {
 	types: string;
+	import: string;
 	default: string;
 }
 /**
@@ -239,6 +258,8 @@ declare const pluginConfigSchema: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.
 */
 declare const typeScriptOptionsSchema: z.ZodDefault<z.ZodObject<{
 	declaration: z.ZodDefault<z.ZodBoolean>;
+	isolatedDeclarations: z.ZodDefault<z.ZodBoolean>;
+	maxMemory: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>>;
 /**
 * Schema for Biome configuration options
@@ -257,6 +278,8 @@ declare const fotConfigSchema: z.ZodObject<{
 	external: z.ZodDefault<z.ZodArray<z.ZodString>>;
 	typescript: z.ZodDefault<z.ZodObject<{
 		declaration: z.ZodDefault<z.ZodBoolean>;
+		isolatedDeclarations: z.ZodDefault<z.ZodBoolean>;
+		maxMemory: z.ZodOptional<z.ZodNumber>;
 	}, z.core.$strip>>;
 	biome: z.ZodDefault<z.ZodObject<{
 		enabled: z.ZodDefault<z.ZodBoolean>;

package/dist/index.js

@@ -15,8 +15,10 @@ var pluginConfigSchema = z.union([
   return { name: val.name, enabled: val.enabled ?? true };
 });
 var typeScriptOptionsSchema = z.object({
-  declaration: z.boolean().default(true)
-}).default({ declaration: true });
+  declaration: z.boolean().default(true),
+  isolatedDeclarations: z.boolean().default(false),
+  maxMemory: z.number().int().positive().optional()
+}).default({ declaration: true, isolatedDeclarations: false });
 var biomeOptionsSchema = z.object({
   enabled: z.boolean().default(true)
 }).default({ enabled: true });
@@ -82,6 +84,7 @@ function generatePackageJson(libraryName, version, config, customDependencies) {
   const exports = {
     ".": {
       types: "./dist/index.d.ts",
+      import: "./dist/index.js",
       default: "./dist/index.js"
     }
   };
@@ -89,6 +92,7 @@ function generatePackageJson(libraryName, version, config, customDependencies) {
     if (plugin.enabled !== false) {
       exports[`./plugins/${plugin.name}`] = {
         types: `./dist/plugins/${plugin.name}/index.d.ts`,
+        import: `./dist/plugins/${plugin.name}/index.js`,
         default: `./dist/plugins/${plugin.name}/index.js`
       };
     }
@@ -123,11 +127,13 @@ function generatePackageJson(libraryName, version, config, customDependencies) {
 }
 // src/generators/tsconfig.ts
 function generateTSConfig(config) {
+  const enabledPlugins = config.plugins.filter((p) => p.enabled !== false);
+  const pluginExcludes = enabledPlugins.map((p) => `src/plugins/${p.name}`);
   return {
     compilerOptions: {
       allowImportingTsExtensions: true,
       declaration: config.typescript.declaration,
-      isolatedDeclarations: false,
+      isolatedDeclarations: config.typescript.isolatedDeclarations,
       module: "Preserve",
       moduleDetection: "force",
       moduleResolution: "bundler",
@@ -143,7 +149,7 @@ function generateTSConfig(config) {
       target: "ES2023",
       verbatimModuleSyntax: true
     },
-    exclude: ["node_modules", "dist", "bunup.config.ts"],
+    exclude: ["node_modules", "dist", "bunup.config.ts", ...pluginExcludes],
     include: ["src/**/*"]
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
    "name": "@f-o-t/config",
-   "version": "0.1.0",
+   "version": "1.0.4",
    "description": "Standardized configuration for F-O-T libraries",
    "type": "module",
    "module": "./dist/index.js",
@@ -11,13 +11,13 @@
          "import": {
             "default": "./dist/index.js",
             "types": "./dist/index.d.ts"
-         },
-         "types": "./src/index.ts"
+         }
       },
       "./package.json": "./package.json"
    },
    "files": [
-      "dist"
+      "dist",
+      "src"
    ],
    "scripts": {
       "build": "bunup",
@@ -27,10 +27,10 @@
       "test": "bun test",
       "test:coverage": "bun test --coverage",
       "test:watch": "bun test --watch",
-      "typecheck": "tsc"
+      "typecheck": "tsc --noEmit"
    },
    "dependencies": {
-      "zod": "4.3.6"
+      "zod": "^4.3.6"
    },
    "devDependencies": {
       "@biomejs/biome": "2.3.12",

package/src/factory.ts

@@ -0,0 +1,24 @@
+import { fotConfigSchema } from "./schemas";
+import type { FotConfig, ResolvedFotConfig } from "./types";
+
+/**
+ * Factory function to define a FOT library configuration
+ * Validates the config against the schema and applies defaults
+ *
+ * @param config - The library configuration
+ * @returns The validated and normalized configuration with defaults applied
+ * @throws {Error} If the configuration is invalid
+ */
+export function defineFotConfig(config: FotConfig = {}): ResolvedFotConfig {
+   // Validate against schema (schema handles defaults and normalization)
+   const result = fotConfigSchema.safeParse(config);
+
+   if (!result.success) {
+      const errors = result.error.issues
+         .map((err) => `${err.path.join(".")}: ${err.message}`)
+         .join(", ");
+      throw new Error(`Invalid FOT configuration: ${errors}`);
+   }
+
+   return result.data;
+}

package/src/generators/biome.ts

@@ -0,0 +1,84 @@
+import type { ResolvedFotConfig } from "../types";
+
+/**
+ * Biome configuration structure
+ */
+export interface BiomeConfig {
+   $schema: string;
+   vcs: {
+      enabled: boolean;
+      clientKind: string;
+      useIgnoreFile: boolean;
+      defaultBranch: string;
+   };
+   files: {
+      ignoreUnknown: boolean;
+      ignore: string[];
+   };
+   formatter: {
+      enabled: boolean;
+      indentStyle: string;
+      indentWidth: number;
+      lineWidth: number;
+   };
+   organizeImports: {
+      enabled: boolean;
+   };
+   linter: {
+      enabled: boolean;
+      rules: {
+         recommended: boolean;
+      };
+   };
+   javascript: {
+      formatter: {
+         quoteStyle: string;
+         semicolons: string;
+         trailingCommas: string;
+      };
+   };
+}
+
+/**
+ * Generate a biome.json file from a resolved FOT configuration
+ *
+ * @param config - The resolved FOT configuration
+ * @returns The generated biome.json object
+ */
+export function generateBiomeConfig(config: ResolvedFotConfig): BiomeConfig {
+   return {
+      $schema: "https://biomejs.dev/schemas/1.9.4/schema.json",
+      vcs: {
+         enabled: true,
+         clientKind: "git",
+         useIgnoreFile: true,
+         defaultBranch: "main",
+      },
+      files: {
+         ignoreUnknown: false,
+         ignore: ["node_modules", "dist", "*.config.ts"],
+      },
+      formatter: {
+         enabled: config.biome.enabled,
+         indentStyle: "tab",
+         indentWidth: 2,
+         lineWidth: 80,
+      },
+      organizeImports: {
+         enabled: true,
+      },
+      linter: {
+         enabled: config.biome.enabled,
+         rules: {
+            recommended: true,
+         },
+      },
+      javascript: {
+         formatter: {
+            quoteStyle: "double",
+            semicolons: "always",
+            trailingCommas: "all",
+         },
+      },
+   };
+}

package/src/generators/index.ts

@@ -0,0 +1,3 @@
+export * from "./biome";
+export * from "./package-json";
+export * from "./tsconfig";

package/src/generators/package-json.ts

@@ -0,0 +1,100 @@
+import type { ResolvedFotConfig } from "../types";
+
+/**
+ * Package.json export configuration.
+ * Includes "import" condition so bundlers/Vite can resolve ESM entries
+ * under conditions like ["module", "browser", "import"].
+ */
+export interface PackageExport {
+   types: string;
+   import: string;
+   default: string;
+}
+
+/**
+ * Package.json structure
+ */
+export interface PackageJson {
+   name: string;
+   version: string;
+   type: "module";
+   main: string;
+   types: string;
+   exports: Record<string, PackageExport>;
+   scripts: Record<string, string>;
+   dependencies?: Record<string, string>;
+   devDependencies: Record<string, string>;
+   repository: {
+      type: "git";
+      url: string;
+      directory: string;
+   };
+}
+
+/**
+ * Generate a package.json file from a resolved FOT configuration
+ *
+ * @param libraryName - The name of the library (without @f-o-t/ prefix)
+ * @param version - The version of the library
+ * @param config - The resolved FOT configuration
+ * @param customDependencies - Optional custom dependencies to include
+ * @returns The generated package.json object
+ */
+export function generatePackageJson(
+   libraryName: string,
+   version: string,
+   config: ResolvedFotConfig,
+   customDependencies?: Record<string, string>,
+): PackageJson {
+   // Generate exports for main entry point
+   const exports: Record<string, PackageExport> = {
+      ".": {
+         types: "./dist/index.d.ts",
+         import: "./dist/index.js",
+         default: "./dist/index.js",
+      },
+   };
+
+   // Generate exports for each plugin
+   for (const plugin of config.plugins) {
+      if (plugin.enabled !== false) {
+         exports[`./plugins/${plugin.name}`] = {
+            types: `./dist/plugins/${plugin.name}/index.d.ts`,
+            import: `./dist/plugins/${plugin.name}/index.js`,
+            default: `./dist/plugins/${plugin.name}/index.js`,
+         };
+      }
+   }
+
+   // Build package.json structure
+   const pkg: PackageJson = {
+      name: `@f-o-t/${libraryName}`,
+      version,
+      type: "module",
+      main: "./dist/index.js",
+      types: "./dist/index.d.ts",
+      exports,
+      scripts: {
+         build: "fot build",
+         test: "fot test",
+         lint: "fot lint",
+         format: "fot format",
+      },
+      devDependencies: {
+         "@f-o-t/cli": "workspace:*",
+         "@f-o-t/config": "workspace:*",
+      },
+      repository: {
+         type: "git",
+         url: "https://github.com/F-O-T/libraries.git",
+         directory: `libraries/${libraryName}`,
+      },
+   };
+
+   // Add custom dependencies if provided
+   if (customDependencies && Object.keys(customDependencies).length > 0) {
+      pkg.dependencies = customDependencies;
+   }
+
+   return pkg;
+}

package/src/generators/tsconfig.ts

@@ -0,0 +1,66 @@
+import type { ResolvedFotConfig } from "../types";
+
+/**
+ * TypeScript configuration structure
+ */
+export interface TSConfig {
+   compilerOptions: {
+      allowImportingTsExtensions: boolean;
+      declaration: boolean;
+      isolatedDeclarations: boolean;
+      module: string;
+      moduleDetection: string;
+      moduleResolution: string;
+      noEmit: boolean;
+      noFallthroughCasesInSwitch: boolean;
+      noImplicitOverride: boolean;
+      noPropertyAccessFromIndexSignature: boolean;
+      noUncheckedIndexedAccess: boolean;
+      noUnusedLocals: boolean;
+      noUnusedParameters: boolean;
+      skipLibCheck: boolean;
+      strict: boolean;
+      target: string;
+      verbatimModuleSyntax: boolean;
+   };
+   exclude: string[];
+   include: string[];
+}
+
+/**
+ * Generate a tsconfig.json file from a resolved FOT configuration
+ *
+ * @param config - The resolved FOT configuration
+ * @returns The generated tsconfig.json object
+ */
+export function generateTSConfig(config: ResolvedFotConfig): TSConfig {
+   // Exclude plugin directories from main tsconfig so their dependencies
+   // (e.g., @f-o-t/condition-evaluator) don't get type-checked in the main pass.
+   // Plugin declarations are handled separately by the build system.
+   const enabledPlugins = config.plugins.filter((p) => p.enabled !== false);
+   const pluginExcludes = enabledPlugins.map((p) => `src/plugins/${p.name}`);
+
+   return {
+      compilerOptions: {
+         allowImportingTsExtensions: true,
+         declaration: config.typescript.declaration,
+         isolatedDeclarations: config.typescript.isolatedDeclarations,
+         module: "Preserve",
+         moduleDetection: "force",
+         moduleResolution: "bundler",
+         noEmit: true,
+         noFallthroughCasesInSwitch: true,
+         noImplicitOverride: true,
+         noPropertyAccessFromIndexSignature: false,
+         noUncheckedIndexedAccess: true,
+         noUnusedLocals: false,
+         noUnusedParameters: false,
+         skipLibCheck: true,
+         strict: true,
+         target: "ES2023",
+         verbatimModuleSyntax: true,
+      },
+      exclude: ["node_modules", "dist", "bunup.config.ts", ...pluginExcludes],
+      include: ["src/**/*"],
+   };
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./factory.ts";
+export * from "./generators/index.ts";
+export * from "./schemas.ts";
+export * from "./types.ts";

package/src/schemas.ts

@@ -0,0 +1,82 @@
+import { z } from "zod";
+
+/**
+ * Regex for validating npm package names (scoped and unscoped)
+ * - Must be lowercase
+ * - Can contain hyphens, dots, underscores
+ * - Scoped packages: @scope/name
+ * - Cannot start with dot or underscore
+ */
+const packageNameRegex =
+   /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+
+/**
+ * Schema for build output formats
+ */
+export const buildFormatSchema = z.enum(["esm", "cjs"]);
+
+/**
+ * Schema for plugin configuration
+ * Accepts either a string (plugin name) or a config object
+ */
+export const pluginConfigSchema = z
+   .union([
+      z.string(),
+      z.object({
+         name: z.string(),
+         enabled: z.boolean().default(true),
+      }),
+   ])
+   .transform((val) => {
+      if (typeof val === "string") {
+         return { name: val, enabled: true };
+      }
+      return { name: val.name, enabled: val.enabled ?? true };
+   });
+
+/**
+ * Schema for TypeScript compiler options
+ */
+export const typeScriptOptionsSchema = z
+   .object({
+      declaration: z.boolean().default(true),
+      isolatedDeclarations: z.boolean().default(false),
+      maxMemory: z.number().int().positive().optional(),
+   })
+   .default({ declaration: true, isolatedDeclarations: false });
+
+/**
+ * Schema for Biome configuration options
+ */
+export const biomeOptionsSchema = z
+   .object({
+      enabled: z.boolean().default(true),
+   })
+   .default({ enabled: true });
+
+/**
+ * Schema for FOT configuration
+ */
+export const fotConfigSchema = z.object({
+   formats: z.array(buildFormatSchema).default(["esm"]),
+   external: z
+      .array(
+         z.string().regex(packageNameRegex, {
+            message: "Invalid package name format",
+         }),
+      )
+      .default([]),
+   typescript: typeScriptOptionsSchema,
+   biome: biomeOptionsSchema,
+   plugins: z.array(pluginConfigSchema).default([]),
+});
+
+/**
+ * Type for input configuration (before validation and defaults)
+ */
+export type FotConfigInput = z.input<typeof fotConfigSchema>;
+
+/**
+ * Type for output configuration (after validation and defaults)
+ */
+export type FotConfigOutput = z.output<typeof fotConfigSchema>;

package/src/types.ts

@@ -0,0 +1,112 @@
+/**
+ * Build output formats
+ */
+export type BuildFormat = "esm" | "cjs";
+
+/**
+ * TypeScript compiler options for the build
+ */
+export interface TypeScriptOptions {
+   /**
+    * Generate .d.ts declaration files
+    * @default true
+    */
+   declaration?: boolean;
+   /**
+    * Use isolated declarations mode for faster, more memory-efficient declaration generation
+    * Requires TypeScript 5.5+
+    * @default false
+    */
+   isolatedDeclarations?: boolean;
+   /**
+    * Maximum memory (in MB) to allocate for TypeScript declaration generation
+    * Useful for large libraries with complex types
+    * @default undefined (uses Node.js default ~2GB)
+    */
+   maxMemory?: number;
+}
+
+/**
+ * Biome configuration options
+ */
+export interface BiomeOptions {
+   /**
+    * Enable Biome for linting/formatting
+    * @default true
+    */
+   enabled?: boolean;
+}
+
+/**
+ * Plugin configuration
+ */
+export interface PluginConfig {
+   /**
+    * Name of the plugin
+    */
+   name: string;
+   /**
+    * Whether the plugin is enabled
+    * @default true
+    */
+   enabled?: boolean;
+}
+
+/**
+ * User-provided configuration for FOT libraries
+ */
+export interface FotConfig {
+   /**
+    * Build output formats
+    * @default ["esm"]
+    */
+   formats?: BuildFormat[];
+   /**
+    * External dependencies that should not be bundled
+    * @default []
+    */
+   external?: string[];
+   /**
+    * TypeScript options
+    */
+   typescript?: TypeScriptOptions;
+   /**
+    * Biome options
+    */
+   biome?: BiomeOptions;
+   /**
+    * Plugins to load - can be plugin names as strings or config objects
+    * @default []
+    */
+   plugins?: (string | PluginConfig)[];
+}
+
+/**
+ * Resolved configuration with all defaults applied
+ */
+export interface ResolvedFotConfig {
+   /**
+    * Build output formats
+    */
+   formats: BuildFormat[];
+   /**
+    * External dependencies that should not be bundled
+    */
+   external: string[];
+   /**
+    * TypeScript options
+    */
+   typescript: {
+      declaration: boolean;
+      isolatedDeclarations: boolean;
+      maxMemory?: number;
+   };
+   /**
+    * Biome options
+    */
+   biome: Required<BiomeOptions>;
+   /**
+    * Plugins to load (normalized to config objects)
+    */
+   plugins: PluginConfig[];
+}