typescript migration: all source files, not including tests and build scripts

.c8rc.json

@@ -1,7 +1,7 @@
 {
   "all": true,
-  "include": ["src/**/*.js"],
-  "exclude": ["src/schemas/dereferenceSchemas.js"],
+  "include": ["dist/**/*.js"],
+  "exclude": ["dist/types/generated/**/*.js", "dist/**/*.d.ts"],
   "reporter": ["text", "lcov", "json", "json-summary"],
   "report-dir": "coverage",
   "check-coverage": false

.github/workflows/npm-test.yml

@@ -50,7 +50,7 @@ jobs:
           cache-dependency-path: package-lock.json
           node-version: 20
       - run: npm ci
-      - run: npm run dereferenceSchemas
+      - run: npm run dereferenceSchemas && npm run generate:types && npm run compile
       - name: Run tests with coverage
         run: npm run test:coverage
       - name: Check coverage ratchet

README.md

@@ -30,6 +30,36 @@ This package exports the following components:
 - `readFile` - File reading utilities
 - `transformToSchemaKey` - Schema key transformation
 
+### TypeScript Support
+
+Full TypeScript support with exported types:
+
+```typescript
+import { 
+  validate, 
+  ValidateOptions, 
+  ValidateResult,
+  resolvePaths,
+  ResolvePathsOptions
+} from 'doc-detective-common';
+```
+
+**Documentation:**
+- [TypeScript Migration Guide](./docs/typescript-migration.md) - Complete guide for TypeScript users
+- [TypeScript Examples](./docs/typescript-examples.md) - Runnable code examples
+
+### JavaScript Usage
+
+Works seamlessly with JavaScript (CommonJS or ESM):
+
+```javascript
+// CommonJS
+const { validate, schemas } = require('doc-detective-common');
+
+// ESM
+import { validate, schemas } from 'doc-detective-common';
+```
+
 ## 🧪 Development
 
 ```bash
@@ -45,4 +75,4 @@ npm run build
 
 ## 📄 License
 
-AGPL-3.0-only
+AGPL-3.0-only

dist/files.d.ts

@@ -0,0 +1,16 @@
+export interface ReadFileOptions {
+    fileURLOrPath: string;
+}
+/**
+ * Reads and parses content from a remote URL or local file path, supporting JSON and YAML formats.
+ *
+ * Attempts to parse the file content as JSON first, then YAML. If both parsing attempts fail, returns the raw content as a string. Returns `null` if the file cannot be read.
+ *
+ * @param options - Options object
+ * @param options.fileURLOrPath - The URL or local file path to read.
+ * @returns Parsed object for JSON or YAML files, raw string for other formats, or `null` if reading fails.
+ *
+ * @throws {Error} If {@link fileURLOrPath} is missing, not a string, or is an empty string.
+ */
+export declare function readFile({ fileURLOrPath }: ReadFileOptions): Promise<unknown | string | null>;
+//# sourceMappingURL=files.d.ts.map

dist/index.d.ts

@@ -0,0 +1,5 @@
+export { schemas, SchemaKey, Schema } from "./schemas";
+export { validate, transformToSchemaKey, ValidateOptions, ValidateResult, TransformOptions } from "./validate";
+export { resolvePaths, ResolvePathsOptions } from "./resolvePaths";
+export { readFile, ReadFileOptions } from "./files";
+//# sourceMappingURL=index.d.ts.map

dist/index.mjs

@@ -0,0 +1,4 @@
+// ESM wrapper for CommonJS output
+import cjsModule from './index.js';
+export const { schemas, validate, transformToSchemaKey, resolvePaths, readFile } = cjsModule;
+export default cjsModule;

dist/resolvePaths.d.ts

@@ -0,0 +1,28 @@
+type RelativePathBase = "file" | "cwd";
+type ObjectType = "config" | "spec";
+export interface ResolvePathsOptions {
+    config: {
+        relativePathBase: RelativePathBase;
+    };
+    object: Record<string, any>;
+    filePath: string;
+    nested?: boolean;
+    objectType?: ObjectType;
+}
+/**
+ * Convert recognized relative path properties in a config or spec object to absolute paths.
+ *
+ * Traverses the provided object (recursing into nested objects and arrays), resolving fields that represent filesystem paths according to the provided config.relativePathBase and reference filePath. On top-level calls the function infers whether the object is a config or spec via schema validation; for nested calls objectType must be provided.
+ *
+ * @param options - Options for path resolution.
+ * @param options.config - Configuration containing settings such as `relativePathBase`.
+ * @param options.object - The config or spec object whose path properties will be resolved.
+ * @param options.filePath - Reference file or directory used to resolve relative paths.
+ * @param options.nested - True when invoked recursively for nested objects.
+ * @param options.objectType - 'config' or 'spec'; required for nested invocations to select which properties to resolve.
+ * @returns The same object with applicable path properties converted to absolute paths.
+ * @throws {Error} If the top-level object matches neither config nor spec schema, or if `objectType` is missing for nested calls.
+ */
+export declare function resolvePaths({ config, object, filePath, nested, objectType, }: ResolvePathsOptions): Promise<Record<string, any>>;
+export {};
+//# sourceMappingURL=resolvePaths.d.ts.map