@skmtc/core 0.28.7 → 0.30.1

package/esm/helpers/isImported.d.ts

@@ -1,81 +1,17 @@
 /**
- * Determines whether two file paths represent different locations (import required).
+ * Whether two workspace paths name different files, so a symbol from one
+ * must be imported into the other.
  *
- * This utility function normalizes two file paths and compares them to determine
- * if they represent different files. It's used throughout the SKMTC system to
- * decide when import statements are needed - if two paths are different, an
- * import is required to access symbols from one file in another.
+ * Both are canonicalized with {@link normalizeWorkspacePath}, so every
+ * spelling of one file compares equal: `@/`, `./`, the bare form, and
+ * Windows separators. Throws, as that does, for a path that cannot name a
+ * file below `basePath` (a `..` segment, a Windows drive path).
  *
- * The function handles path normalization to ensure consistent comparisons
- * across different operating systems and path formats (handling './' vs absolute
- * paths, different separators, etc.).
- *
- * @param pathOne - The first file path to compare
- * @param pathTwo - The second file path to compare
- * @returns `true` if the paths are different (import needed), `false` if they're the same file
- *
- * @example Basic path comparison
- * ```typescript
- * import { isImported } from '@skmtc/core';
- *
- * // Same file, no import needed
- * console.log(isImported('./src/user.ts', './src/user.ts')); // false
- *
- * // Different files, import needed
- * console.log(isImported('./src/user.ts', './src/product.ts')); // true
- * ```
- *
- * @example Path normalization handling
- * ```typescript
- * // These all represent the same file after normalization
- * console.log(isImported('./src/user.ts', 'src/user.ts')); // false
- * console.log(isImported('src/./user.ts', 'src/user.ts')); // false
- * console.log(isImported('src/models/../user.ts', 'src/user.ts')); // false
- * ```
- *
- * @example Usage in import decision logic
+ * @example
  * ```typescript
- * class FileGenerator {
- *   addImportIfNeeded(
- *     sourceFile: string,
- *     targetFile: string,
- *     importName: string
- *   ) {
- *     if (isImported(sourceFile, targetFile)) {
- *       // Files are different, add import
- *       this.addImport(sourceFile, targetFile, importName);
- *       console.log(`Added import: ${importName} from ${targetFile}`);
- *     } else {
- *       // Same file, no import needed
- *       console.log(`No import needed - same file: ${sourceFile}`);
- *     }
- *   }
- * }
- * ```
- *
- * @example Cross-platform path handling
- * ```typescript
- * // Works consistently across platforms
- * const windowsPath = 'src\\models\\user.ts';
- * const unixPath = 'src/models/user.ts';
- *
- * console.log(isImported(windowsPath, unixPath)); // false (same file)
- * ```
- *
- * @example In generator context
- * ```typescript
- * class ModelGenerator {
- *   generateModel(modelPath: string, referencePath: string) {
- *     const definition = this.createModelDefinition();
- *
- *     if (isImported(modelPath, referencePath)) {
- *       // Need to import the referenced model
- *       definition.addImport(referencePath, 'ReferencedModel');
- *     }
- *
- *     return definition;
- *   }
- * }
+ * isImported('@/src/user.ts', './src/user.ts')    // false — one file
+ * isImported('src\\user.ts', 'src/user.ts')       // false — one file
+ * isImported('@/src/user.ts', '@/src/product.ts') // true
  * ```
  */
 export declare const isImported: (pathOne: string, pathTwo: string) => boolean;

package/esm/helpers/isImported.js

@@ -1,84 +1,20 @@
-import { normalize } from '../deps/jsr.io/@std/path/1.1.6/normalize.js';
+import { normalizeWorkspacePath } from './normalizeWorkspacePath.js';
 /**
- * Determines whether two file paths represent different locations (import required).
+ * Whether two workspace paths name different files, so a symbol from one
+ * must be imported into the other.
  *
- * This utility function normalizes two file paths and compares them to determine
- * if they represent different files. It's used throughout the SKMTC system to
- * decide when import statements are needed - if two paths are different, an
- * import is required to access symbols from one file in another.
+ * Both are canonicalized with {@link normalizeWorkspacePath}, so every
+ * spelling of one file compares equal: `@/`, `./`, the bare form, and
+ * Windows separators. Throws, as that does, for a path that cannot name a
+ * file below `basePath` (a `..` segment, a Windows drive path).
  *
- * The function handles path normalization to ensure consistent comparisons
- * across different operating systems and path formats (handling './' vs absolute
- * paths, different separators, etc.).
- *
- * @param pathOne - The first file path to compare
- * @param pathTwo - The second file path to compare
- * @returns `true` if the paths are different (import needed), `false` if they're the same file
- *
- * @example Basic path comparison
- * ```typescript
- * import { isImported } from '@skmtc/core';
- *
- * // Same file, no import needed
- * console.log(isImported('./src/user.ts', './src/user.ts')); // false
- *
- * // Different files, import needed
- * console.log(isImported('./src/user.ts', './src/product.ts')); // true
- * ```
- *
- * @example Path normalization handling
- * ```typescript
- * // These all represent the same file after normalization
- * console.log(isImported('./src/user.ts', 'src/user.ts')); // false
- * console.log(isImported('src/./user.ts', 'src/user.ts')); // false
- * console.log(isImported('src/models/../user.ts', 'src/user.ts')); // false
- * ```
- *
- * @example Usage in import decision logic
+ * @example
  * ```typescript
- * class FileGenerator {
- *   addImportIfNeeded(
- *     sourceFile: string,
- *     targetFile: string,
- *     importName: string
- *   ) {
- *     if (isImported(sourceFile, targetFile)) {
- *       // Files are different, add import
- *       this.addImport(sourceFile, targetFile, importName);
- *       console.log(`Added import: ${importName} from ${targetFile}`);
- *     } else {
- *       // Same file, no import needed
- *       console.log(`No import needed - same file: ${sourceFile}`);
- *     }
- *   }
- * }
- * ```
- *
- * @example Cross-platform path handling
- * ```typescript
- * // Works consistently across platforms
- * const windowsPath = 'src\\models\\user.ts';
- * const unixPath = 'src/models/user.ts';
- *
- * console.log(isImported(windowsPath, unixPath)); // false (same file)
- * ```
- *
- * @example In generator context
- * ```typescript
- * class ModelGenerator {
- *   generateModel(modelPath: string, referencePath: string) {
- *     const definition = this.createModelDefinition();
- *
- *     if (isImported(modelPath, referencePath)) {
- *       // Need to import the referenced model
- *       definition.addImport(referencePath, 'ReferencedModel');
- *     }
- *
- *     return definition;
- *   }
- * }
+ * isImported('@/src/user.ts', './src/user.ts')    // false — one file
+ * isImported('src\\user.ts', 'src/user.ts')       // false — one file
+ * isImported('@/src/user.ts', '@/src/product.ts') // true
  * ```
  */
 export const isImported = (pathOne, pathTwo) => {
-    return normalize(pathOne) !== normalize(pathTwo);
+    return normalizeWorkspacePath(pathOne) !== normalizeWorkspacePath(pathTwo);
 };

package/esm/helpers/naming.d.ts

@@ -4,7 +4,7 @@ import type { Method } from '../types/Method.js';
  * Determines the endpoint type based on HTTP method.
  *
  * @param operation - The OpenAPI operation to analyze
- * @returns 'query' for GET operations, 'mutation' for all others
+ * @returns 'query' for GET and QUERY operations, 'mutation' for all others
  *
  * @example
  * ```typescript
@@ -67,6 +67,7 @@ export declare const toArgsName: (operation: OasOperation) => string;
  * console.log(toMethodVerb('put'));  // 'Update'
  * console.log(toMethodVerb('get'));  // 'get'
  * console.log(toMethodVerb('delete')); // 'delete'
+ * console.log(toMethodVerb('query')); // 'Query'
  * ```
  */
 export declare const toMethodVerb: (method: Method) => string;

package/esm/helpers/naming.js

@@ -3,7 +3,7 @@ import { camelCase, capitalize } from './strings.js';
  * Determines the endpoint type based on HTTP method.
  *
  * @param operation - The OpenAPI operation to analyze
- * @returns 'query' for GET operations, 'mutation' for all others
+ * @returns 'query' for GET and QUERY operations, 'mutation' for all others
  *
  * @example
  * ```typescript
@@ -15,7 +15,8 @@ import { camelCase, capitalize } from './strings.js';
  * ```
  */
 export const toEndpointType = (operation) => {
-    return operation.method === 'get' ? 'query' : 'mutation';
+    // QUERY is safe and idempotent, like GET.
+    return operation.method === 'get' || operation.method === 'query' ? 'query' : 'mutation';
 };
 /**
  * Generates endpoint name in the `camelCase{method}Api{path}` format.
@@ -78,6 +79,7 @@ export const toArgsName = (operation) => {
  * console.log(toMethodVerb('put'));  // 'Update'
  * console.log(toMethodVerb('get'));  // 'get'
  * console.log(toMethodVerb('delete')); // 'delete'
+ * console.log(toMethodVerb('query')); // 'Query'
  * ```
  */
 export const toMethodVerb = (method) => {

package/esm/helpers/normalizeWorkspacePath.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Options for {@link normalizeWorkspacePath} and {@link toNormalizedWorkspacePath}.
+ */
+export type NormalizeWorkspacePathOptions = {
+    /** Names the generator in the error when the path is rejected. */
+    generatorId?: string;
+};
+/**
+ * Whether a path contains a `..` parent-reference segment. `..` is a parent
+ * reference only as a whole segment — a directory name that merely contains
+ * dots is not flagged.
+ */
+export declare const hasParentSegment: (path: string) => boolean;
+/**
+ * Whether a path is absolute on either host: a POSIX root, a Windows drive
+ * (`C:\`, `C:/`) or a UNC share. Checked on every host, so a client.json
+ * written on Windows is rejected the same way on Linux.
+ */
+export declare const isAbsolutePath: (path: string) => boolean;
+/**
+ * Whether `path` is spelled from the workspace root — `@/`, `./`, a bare
+ * leading `/`, or their Windows forms. An artifact path, never a bare
+ * module specifier such as `zod` or `@tanstack/query`.
+ */
+export declare const hasWorkspaceAnchor: (path: string) => boolean;
+/**
+ * Whether `path` can name a file below `basePath`: not a Windows drive or
+ * UNC path, no `..` segment, and not `basePath` itself. The non-throwing
+ * form of {@link normalizeWorkspacePath}'s checks, for schema validation
+ * and for comparing a module specifier against a file path.
+ */
+export declare const isValidWorkspacePath: (path: string) => boolean;
+/**
+ * The path relative to `basePath`, normalized and with no anchor:
+ * what {@link normalizeWorkspacePath} writes after `@/`, and what
+ * {@link toResolvedArtifactPath} joins onto `basePath`.
+ *
+ * Throws when the path cannot name a file below `basePath`: a Windows
+ * drive or UNC path, a `..` segment (checked as a whole segment before
+ * normalization, so it is never resolved), or a path naming `basePath`
+ * itself (`@/`, `@`, `./`, `.`, `/`, ``).
+ */
+export declare const toNormalizedWorkspacePath: (path: string, { generatorId }?: NormalizeWorkspacePathOptions) => string;
+/**
+ * The one spelling of a workspace path — an export path or a destination
+ * path: `@/` followed by a POSIX path relative to `basePath`.
+ *
+ * A workspace path is a logical path inside the workspace, never a
+ * filesystem path, so it reads the same on every host. A generator may
+ * return one as `@/types/User.ts`, `./types/User.ts`, `/types/User.ts`,
+ * `types/User.ts`, or with Windows separators; the engine stores this form
+ * and nothing else, so file-map keys, import modules and the ejected lookup
+ * always agree. The result is a fixed point.
+ *
+ * Throws in the cases {@link toNormalizedWorkspacePath} throws.
+ *
+ * @example
+ * ```typescript
+ * normalizeWorkspacePath('@\\types\\User.ts') // '@/types/User.ts'
+ * normalizeWorkspacePath('./types/User.ts')   // '@/types/User.ts'
+ * normalizeWorkspacePath('../User.ts')        // throws
+ * ```
+ */
+export declare const normalizeWorkspacePath: (path: string, options?: NormalizeWorkspacePathOptions) => string;

package/esm/helpers/normalizeWorkspacePath.js

@@ -0,0 +1,98 @@
+import { normalize } from '../deps/jsr.io/@std/path/1.1.6/posix/normalize.js';
+import { isAbsolute as isPosixAbsolute } from '../deps/jsr.io/@std/path/1.1.6/posix/is_absolute.js';
+import { isAbsolute as isWindowsAbsolute } from '../deps/jsr.io/@std/path/1.1.6/windows/is_absolute.js';
+import { toWorkspacePath } from './toWorkspacePath.js';
+/**
+ * Whether a path contains a `..` parent-reference segment. `..` is a parent
+ * reference only as a whole segment — a directory name that merely contains
+ * dots is not flagged.
+ */
+export const hasParentSegment = (path) => path.split(/[/\\]/).some(segment => segment === '..');
+/**
+ * Whether a path is absolute on either host: a POSIX root, a Windows drive
+ * (`C:\`, `C:/`) or a UNC share. Checked on every host, so a client.json
+ * written on Windows is rejected the same way on Linux.
+ */
+export const isAbsolutePath = (path) => isPosixAbsolute(path.replaceAll('\\', '/')) || isWindowsAbsolute(path);
+/**
+ * A Windows drive path (`C:\`, `C:/`) or a UNC path (`\\server\share`):
+ * the two absolute forms that can never be relative to `basePath`. A bare
+ * leading `/` is not one — it is an anchor spelling of the workspace root.
+ */
+const isDriveOrUncPath = (path) => /^[A-Za-z]:[\\/]/.test(path) || path.startsWith('\\\\');
+/**
+ * Whether `path` is spelled from the workspace root — `@/`, `./`, a bare
+ * leading `/`, or their Windows forms. An artifact path, never a bare
+ * module specifier such as `zod` or `@tanstack/query`.
+ */
+export const hasWorkspaceAnchor = (path) => /^(@[\\/]|\.[\\/]|[\\/])/.test(path);
+/**
+ * Whether `path` can name a file below `basePath`: not a Windows drive or
+ * UNC path, no `..` segment, and not `basePath` itself. The non-throwing
+ * form of {@link normalizeWorkspacePath}'s checks, for schema validation
+ * and for comparing a module specifier against a file path.
+ */
+export const isValidWorkspacePath = (path) => !isDriveOrUncPath(path) && !hasParentSegment(path) && toBody(path) !== '';
+/**
+ * The path relative to `basePath`, normalized and with no anchor:
+ * what {@link normalizeWorkspacePath} writes after `@/`, and what
+ * {@link toResolvedArtifactPath} joins onto `basePath`.
+ *
+ * Throws when the path cannot name a file below `basePath`: a Windows
+ * drive or UNC path, a `..` segment (checked as a whole segment before
+ * normalization, so it is never resolved), or a path naming `basePath`
+ * itself (`@/`, `@`, `./`, `.`, `/`, ``).
+ */
+export const toNormalizedWorkspacePath = (path, { generatorId } = {}) => {
+    const reject = (reason) => {
+        const source = generatorId ? ` returned by generator '${generatorId}'` : '';
+        throw new Error(`Path '${path}'${source} ${reason}`);
+    };
+    if (isDriveOrUncPath(path)) {
+        return reject('is a Windows drive or UNC path; a workspace path is relative to basePath');
+    }
+    if (hasParentSegment(path)) {
+        return reject('contains a ".." segment; a workspace path is a forward path below basePath');
+    }
+    const body = toBody(path);
+    if (body === '') {
+        return reject('names basePath itself; a workspace path names a file below it');
+    }
+    return body;
+};
+/**
+ * The one spelling of a workspace path — an export path or a destination
+ * path: `@/` followed by a POSIX path relative to `basePath`.
+ *
+ * A workspace path is a logical path inside the workspace, never a
+ * filesystem path, so it reads the same on every host. A generator may
+ * return one as `@/types/User.ts`, `./types/User.ts`, `/types/User.ts`,
+ * `types/User.ts`, or with Windows separators; the engine stores this form
+ * and nothing else, so file-map keys, import modules and the ejected lookup
+ * always agree. The result is a fixed point.
+ *
+ * Throws in the cases {@link toNormalizedWorkspacePath} throws.
+ *
+ * @example
+ * ```typescript
+ * normalizeWorkspacePath('@\\types\\User.ts') // '@/types/User.ts'
+ * normalizeWorkspacePath('./types/User.ts')   // '@/types/User.ts'
+ * normalizeWorkspacePath('../User.ts')        // throws
+ * ```
+ */
+export const normalizeWorkspacePath = (path, options = {}) => `@/${toNormalizedWorkspacePath(path, options)}`;
+/**
+ * Separator swap, then every anchor spelling goes (`@/`, `./`, a leading
+ * `/` — {@link toWorkspacePath}), then POSIX normalize of what is left so
+ * `@//x` and `@/./x` collapse. The anchor goes first so normalize can
+ * never fold it into a name (`@/.` is the root, not a file called `@`).
+ * The root in any spelling is the empty string.
+ */
+const toBody = (path) => {
+    const stripped = toWorkspacePath(path.replaceAll('\\', '/'));
+    if (stripped === '') {
+        return '';
+    }
+    const normalized = normalize(stripped);
+    return normalized === '.' ? '' : normalized;
+};

package/esm/helpers/toResolvedArtifactPath.d.ts

@@ -2,9 +2,11 @@
  * Resolves an artifact's destination path onto `basePath`.
  *
  * `destinationPath` is a workspace path in any spelling
- * ({@link toWorkspacePath}) — `@/models/User.ts` as a generator wrote it,
- * or `./models/User.ts` — and is always joined onto `basePath`; there is no
- * absolute-path escape.
+ * ({@link toNormalizedWorkspacePath}) — `@/models/User.ts` as a generator
+ * wrote it, `./models/User.ts`, or with Windows separators — and is always
+ * joined onto `basePath` with forward slashes, so the artifact key reads
+ * the same on every host. A `..` segment or an absolute path is refused:
+ * every artifact lands below `basePath`, whoever writes it.
  *
  * @module toResolvedArtifactPath
  */
@@ -22,8 +24,9 @@ type ToResolvedArtifactPathArgs = {
     destinationPath: string;
 };
 /**
- * Joins `destinationPath` (canonicalized) onto `basePath`, or onto `./` when
- * `basePath` is undefined.
+ * Joins `destinationPath` (canonicalized) onto `basePath`, or onto the
+ * workspace root when `basePath` is undefined. Throws when
+ * `destinationPath` cannot name a file below `basePath`.
  *
  * @example
  * ```typescript

package/esm/helpers/toResolvedArtifactPath.js

@@ -2,18 +2,22 @@
  * Resolves an artifact's destination path onto `basePath`.
  *
  * `destinationPath` is a workspace path in any spelling
- * ({@link toWorkspacePath}) — `@/models/User.ts` as a generator wrote it,
- * or `./models/User.ts` — and is always joined onto `basePath`; there is no
- * absolute-path escape.
+ * ({@link toNormalizedWorkspacePath}) — `@/models/User.ts` as a generator
+ * wrote it, `./models/User.ts`, or with Windows separators — and is always
+ * joined onto `basePath` with forward slashes, so the artifact key reads
+ * the same on every host. A `..` segment or an absolute path is refused:
+ * every artifact lands below `basePath`, whoever writes it.
  *
  * @module toResolvedArtifactPath
  */
 import "../_dnt.polyfills.js";
-import { join } from '../deps/jsr.io/@std/path/1.1.6/join.js';
+import { join } from '../deps/jsr.io/@std/path/1.1.6/posix/join.js';
+import { toNormalizedWorkspacePath } from './normalizeWorkspacePath.js';
 import { toWorkspacePath } from './toWorkspacePath.js';
 /**
- * Joins `destinationPath` (canonicalized) onto `basePath`, or onto `./` when
- * `basePath` is undefined.
+ * Joins `destinationPath` (canonicalized) onto `basePath`, or onto the
+ * workspace root when `basePath` is undefined. Throws when
+ * `destinationPath` cannot name a file below `basePath`.
  *
  * @example
  * ```typescript
@@ -24,5 +28,5 @@ import { toWorkspacePath } from './toWorkspacePath.js';
  * ```
  */
 export const toResolvedArtifactPath = ({ basePath, destinationPath }) => {
-    return join(basePath ?? './', toWorkspacePath(destinationPath));
+    return join(toWorkspacePath(basePath ?? ''), toNormalizedWorkspacePath(destinationPath));
 };

package/esm/helpers/toWorkspacePath.d.ts

@@ -7,9 +7,9 @@
  * config and examples write it as `./`, and std `normalize` — applied to
  * `File.path` by the drivers — strips `./` but leaves `@/` alone. Anything
  * that compares paths from more than one of those sources (package matching,
- * on-disk resolution) must see all spellings as equal: every leading `@/` or
- * `./` goes, a trailing `/` goes, a Windows `\` is a `/`, and the workspace
- * root itself (`@/`, `./`, `.`, ``) is the empty string. The result is a fixed
+ * on-disk resolution) must see all spellings as equal: every leading `@/`,
+ * `./` or bare `/` goes, a trailing `/` goes, a Windows `\` is a `/`, and the
+ * workspace root itself (`@/`, `@`, `./`, `.`, `/`, ``) is the empty string. The result is a fixed
  * point: canonicalizing it again changes nothing.
  *
  * The `@/` stripped here is Skmtc's **workspace root** — the prefix

package/esm/helpers/toWorkspacePath.js

@@ -7,9 +7,9 @@
  * config and examples write it as `./`, and std `normalize` — applied to
  * `File.path` by the drivers — strips `./` but leaves `@/` alone. Anything
  * that compares paths from more than one of those sources (package matching,
- * on-disk resolution) must see all spellings as equal: every leading `@/` or
- * `./` goes, a trailing `/` goes, a Windows `\` is a `/`, and the workspace
- * root itself (`@/`, `./`, `.`, ``) is the empty string. The result is a fixed
+ * on-disk resolution) must see all spellings as equal: every leading `@/`,
+ * `./` or bare `/` goes, a trailing `/` goes, a Windows `\` is a `/`, and the
+ * workspace root itself (`@/`, `@`, `./`, `.`, `/`, ``) is the empty string. The result is a fixed
  * point: canonicalizing it again changes nothing.
  *
  * The `@/` stripped here is Skmtc's **workspace root** — the prefix
@@ -29,9 +29,9 @@
 export const toWorkspacePath = (path) => {
     const withoutAnchor = path
         .replaceAll('\\', '/')
-        .replace(/^(?:@\/|\.\/)+/, '')
+        .replace(/^(?:@\/|\.\/|\/)+/, '')
         .replace(/\/+$/, '');
-    return withoutAnchor === '.' ? '' : withoutAnchor;
+    return withoutAnchor === '.' || withoutAnchor === '@' ? '' : withoutAnchor;
 };
 /**
  * `path` is `rootPath` itself or a file or folder below it. A root is a

package/esm/mod.d.ts

@@ -118,6 +118,7 @@ export * from './helpers/strings.js';
 export * from './helpers/parseModuleName.js';
 export * from './helpers/toResolvedArtifactPath.js';
 export * from './helpers/toWorkspacePath.js';
+export * from './helpers/normalizeWorkspacePath.js';
 export * from './helpers/matchPackage.js';
 export * from './helpers/withVariant.js';
 export * from './helpers/toVariantList.js';

package/esm/mod.js

@@ -118,6 +118,7 @@ export * from './helpers/strings.js';
 export * from './helpers/parseModuleName.js';
 export * from './helpers/toResolvedArtifactPath.js';
 export * from './helpers/toWorkspacePath.js';
+export * from './helpers/normalizeWorkspacePath.js';
 export * from './helpers/matchPackage.js';
 export * from './helpers/withVariant.js';
 export * from './helpers/toVariantList.js';

package/esm/oas/discriminator/Discriminator.d.ts

@@ -2,10 +2,13 @@ import "../../_dnt.polyfills.js";
 export type DiscriminatorFields = {
     propertyName: string;
     mapping?: Record<string, string>;
+    /** Schema to use when the discriminating value has no mapping entry (OpenAPI 3.2) */
+    defaultMapping?: string;
 };
 export declare class OasDiscriminator {
     oasType: 'discriminator';
     propertyName: string;
     mapping?: Record<string, string>;
+    defaultMapping?: string;
     constructor(fields: DiscriminatorFields);
 }

package/esm/oas/discriminator/Discriminator.js

@@ -19,7 +19,14 @@ export class OasDiscriminator {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "defaultMapping", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         this.propertyName = fields.propertyName;
         this.mapping = fields.mapping;
+        this.defaultMapping = fields.defaultMapping;
     }
 }

package/esm/oas/document/Document.d.ts

@@ -20,6 +20,11 @@ import type { OasExternalDocs } from '../externalDocs/ExternalDocs.js';
 export type DocumentFields = {
     /** OpenAPI specification version (e.g., '3.0.0', '3.1.0') */
     openapi: string;
+    /**
+     * The document's own URI (OpenAPI 3.2 `$self`). Stored only: reference
+     * resolution does not use it.
+     */
+    $self?: string | undefined;
     /** API metadata including title, version, description */
     info: OasInfo;
     /** Array of server objects providing connectivity information */
@@ -215,6 +220,8 @@ export declare class OasDocument {
     set fields(fields: DocumentFields);
     /** OpenAPI specification version */
     get openapi(): string;
+    /** The document's own URI (OpenAPI 3.2 `$self`) */
+    get $self(): string | undefined;
     /** API metadata */
     get info(): OasInfo;
     get servers(): OasServer[] | undefined;

package/esm/oas/document/Document.js

@@ -225,6 +225,13 @@ export class OasDocument {
         }
         return __classPrivateFieldGet(this, _OasDocument_fields, "f").openapi;
     }
+    /** The document's own URI (OpenAPI 3.2 `$self`) */
+    get $self() {
+        if (!__classPrivateFieldGet(this, _OasDocument_fields, "f")) {
+            throw new Error(`Accessing '$self' before fields are set`);
+        }
+        return __classPrivateFieldGet(this, _OasDocument_fields, "f").$self;
+    }
     /** API metadata */
     get info() {
         if (!__classPrivateFieldGet(this, _OasDocument_fields, "f")) {
@@ -311,6 +318,7 @@ export class OasDocument {
     toJSON() {
         return {
             openapi: this.openapi,
+            ...(this.$self !== undefined ? { $self: this.$self } : {}),
             info: this.info,
             servers: this.servers,
             operations: this.operations,

package/esm/oas/example/Example.d.ts

@@ -11,6 +11,10 @@ export type ExampleFields = {
     description?: string;
     /** The example value — absent when the example is given as an `externalValue` */
     value?: unknown;
+    /** The example as data that is valid against its schema (OpenAPI 3.2) */
+    dataValue?: unknown;
+    /** The example in its serialized form (OpenAPI 3.2) */
+    serializedValue?: string;
     /** The external value of the example */
     externalValue?: string;
     /** Custom extension fields (x-* properties) */
@@ -23,6 +27,8 @@ export declare class OasExample {
     summary?: string;
     description?: string;
     value?: unknown;
+    dataValue?: unknown;
+    serializedValue?: string;
     externalValue?: string;
     extensionFields?: Record<string, unknown>;
     constructor(fields: ExampleFields);
@@ -31,5 +37,8 @@ export declare class OasExample {
     /** Returns itself */
     resolve(): OasExample;
     resolveOnce(): OasExample;
-    toJsonSchema(_options: ToJsonSchemaOptions): OpenAPIV3.ExampleObject;
+    toJsonSchema(_options: ToJsonSchemaOptions): OpenAPIV3.ExampleObject & {
+        dataValue?: unknown;
+        serializedValue?: string;
+    };
 }