From 2a140a13edd7c92c847172d90bb1b47fba7be67d Mon Sep 17 00:00:00 2001 From: Okiki Ojo Date: Tue, 18 Aug 2026 12:16:16 -0400 Subject: [PATCH] docs(api): make the root contract inspectable and doc-lint clean Previous root exports leaked private helper types through schema-derived aliases and nested support contracts, which made the public API harder to inspect and kept deno doc --lint from passing. Define stable public-facing types for the root surface, export the supporting contracts that callers need to understand, and keep the Zod schema layer on explicit subpaths instead of mixing it into the root package narrative. --- mod.ts | 44 ++++++++++- src/context.ts | 2 +- src/driver/definition.ts | 91 ++++++++++++++++++++--- src/driver/file.ts | 32 +++++++- src/plan.ts | 122 +++++++++++++++++++++++++++++-- src/schema.ts | 154 +++++++++++++++++++++++++++++++++------ 6 files changed, 400 insertions(+), 45 deletions(-) diff --git a/mod.ts b/mod.ts index b593562..a89669b 100644 --- a/mod.ts +++ b/mod.ts @@ -48,6 +48,7 @@ export { openFileSystem } from "./src/adapter/opfs.ts"; export { FileSystemError, getErrorMessage, getErrorName, toFileSystemError } from "./src/error.ts"; export { getOpfsContext } from "./src/context.ts"; export { probeOpfs } from "./src/probe.ts"; +export { WritableFileStream } from "./src/handle.ts"; export type { CopyOptionsType, DirectoryEntryType, @@ -71,7 +72,10 @@ export type { WalkOptionsType, WriteOptionsType, } from "./src/filesystem.ts"; +export type { AdapterType, FileSystemOptionsType } from "./src/adapter/definition.ts"; +export type { OpenFileSystemOptionsType } from "./src/adapter/opfs.ts"; export type { + CreateWritableOptionsType, DirectoryHandleType, FileHandleType, HandleCreateOptionsType, @@ -84,6 +88,18 @@ export type { export type { SyncFileType } from "./src/sync.ts"; export type { WritableFileType } from "./src/writable.ts"; export type { WriteDataType } from "./src/stream.ts"; +export type { BrowserGlobalType } from "./src/context.ts"; +export type { + FileDriverCopyOptionsType, + FileDriverDirectoryEntryType, + FileDriverMoveOptionsType, + FileDriverReadOptionsType, + FileDriverSignalOptionsType, + FileDriverStatType, + FileDriverSyncFileType, + FileDriverWritableFileType, + FileDriverWriteOptionsType, +} from "./src/driver/file.ts"; export type { AdapterCapabilitiesType, AdapterLimitsType, @@ -101,15 +117,35 @@ export type { MetricsModeType, OpfsContextType, OptimizationType, + PathType, PartitionModeType, RequirementStateType, RequirementType, SupportModeType, WriteModeType, } from "./src/schema.ts"; -export type { FileSystemOptionsType } from "./src/adapter/definition.ts"; -export type { InspectionType, SupportType, WriteSupportType } from "./src/capability.ts"; +export type { + ActionKindType, + ActionType, + DriverPlanInputType, + DriverInspectionType, + DriverOperationType, + DriverPlanType, + DriverType, + ProblemLayerType, + ProblemSeverityType, + ProblemType, +} from "./src/driver/definition.ts"; +export type { AdapterInspectionType, InspectionType, SupportType, WriteSupportType } from "./src/capability.ts"; export type { DriverMetricsType, MetricEntryType, MetricOperationType, MetricsType } from "./src/metrics.ts"; -export { PlanInputSchema, PlanOperationSchema, PlanSchema, WriteSourceSchema } from "./src/plan.ts"; -export type { PlanInputType, PlanOperationType, PlanType, WriteSourceType } from "./src/plan.ts"; +export type { + CopyPlanInputType, + MovePlanInputType, + PlanInputType, + PlanOperationType, + PlanType, + ReadPlanInputType, + WritePlanInputType, + WriteSourceType, +} from "./src/plan.ts"; export type { OpfsCapabilitiesType, OpfsProbeErrorType, OpfsStorageEstimateType } from "./src/probe.ts"; diff --git a/src/context.ts b/src/context.ts index a8daf41..29fa276 100644 --- a/src/context.ts +++ b/src/context.ts @@ -6,7 +6,7 @@ import type { OpfsContextType } from "./schema.ts"; * The library intentionally avoids browser-name checks. Runtime placement is * inferred from the globals that define Window and Worker execution models. */ -interface BrowserGlobalType { +export interface BrowserGlobalType { /** Window document marker. */ readonly document?: object; /** ServiceWorker registration marker. */ diff --git a/src/driver/definition.ts b/src/driver/definition.ts index d6c2305..a27ca0a 100644 --- a/src/driver/definition.ts +++ b/src/driver/definition.ts @@ -27,7 +27,7 @@ import { export const ProblemLayerSchema = z.enum(["client", "driver", "adapter", "filesystem"]); /** A validated storage problem layer. */ -export type ProblemLayerType = z.output; +export type ProblemLayerType = "client" | "driver" | "adapter" | "filesystem"; /** * Severity of one storage planning problem. @@ -38,7 +38,7 @@ export type ProblemLayerType = z.output; export const ProblemSeveritySchema = z.enum(["info", "warning", "error"]); /** A validated storage planning problem severity. */ -export type ProblemSeverityType = z.output; +export type ProblemSeverityType = "info" | "warning" | "error"; /** * Action a caller can take after a storage preflight result. @@ -59,7 +59,15 @@ export const ActionKindSchema = z.enum([ ]); /** A validated storage planning action. */ -export type ActionKindType = z.output; +export type ActionKindType = + | "partition" + | "change-policy" + | "select-driver" + | "reduce-input" + | "enable-optimization" + | "disable-optimization" + | "probe" + | "retry"; /** * One structured problem found while planning a storage operation. @@ -77,7 +85,18 @@ export const ProblemSchema = z.object({ }).strict(); /** A validated storage planning problem. */ -export type ProblemType = z.output; +export interface ProblemType { + /** Stable machine-readable problem code. */ + readonly code: string; + /** Layer that identified the problem. */ + readonly layer: ProblemLayerType; + /** Severity used by diagnostics and policy. */ + readonly severity: ProblemSeverityType; + /** Human-readable summary of the problem. */ + readonly message: string; + /** Related limit when the problem comes from a specific ceiling or budget. */ + readonly limit?: LimitType | undefined; +} /** * One structured action available to the caller after planning. @@ -93,7 +112,14 @@ export const ActionSchema = z.object({ }).strict(); /** A validated storage planning action. */ -export type ActionType = z.output; +export interface ActionType { + /** Coarse-grained next step the caller can take. */ + readonly kind: ActionKindType; + /** Optional machine-readable qualifier for UI or policy routing. */ + readonly code?: string | undefined; + /** Optional human-readable action detail. */ + readonly detail?: string | undefined; +} /** * Operations that a backend driver can preflight without performing I/O. @@ -105,7 +131,7 @@ export type ActionType = z.output; export const DriverOperationSchema = z.enum(["stat", "read", "write", "list", "copy", "move", "remove"]); /** A validated backend driver operation. */ -export type DriverOperationType = z.output; +export type DriverOperationType = "stat" | "read" | "write" | "list" | "copy" | "move" | "remove"; /** * Concrete operation shape presented to a backend driver planner. @@ -125,7 +151,24 @@ export const DriverPlanInputSchema = z.object({ }).strict(); /** A validated backend driver preflight request. */ -export type DriverPlanInputType = z.output; +export interface DriverPlanInputType { + /** Backend-native operation being preflighted. */ + readonly operation: DriverOperationType; + /** Canonical source path when the operation targets one path. */ + readonly path?: string | undefined; + /** Canonical destination path for copy and move operations. */ + readonly destination?: string | undefined; + /** Caller-known logical byte size when available. */ + readonly size?: number | undefined; + /** Caller-known already-buffered byte count for streamed work. */ + readonly inputBytes?: number | undefined; + /** Physical input source form for write operations. */ + readonly source?: "bytes" | "stream" | undefined; + /** Requested write semantics for write operations. */ + readonly mode?: "replace" | "append" | "update" | undefined; + /** Whether a read request targets a byte range instead of the full file. */ + readonly range?: boolean | undefined; +} /** * Serializable result returned by a backend driver planner. @@ -146,7 +189,22 @@ export const DriverPlanSchema = z.object({ }).strict(); /** A validated backend driver preflight result. */ -export type DriverPlanType = z.output; +export interface DriverPlanType { + /** Backend-native operation that was planned. */ + readonly operation: DriverOperationType; + /** Whether the request can proceed under current facts and policy. */ + readonly supported: boolean; + /** Effective support mode for the backend-native route. */ + readonly support: "native" | "emulated" | "partitioned" | "unsupported"; + /** Physical part or block size when partitioning is involved. */ + readonly partBytes?: number | undefined; + /** Physical part or block count when partitioning is involved. */ + readonly parts?: number | undefined; + /** Structured problems reported by driver planning. */ + readonly problems: readonly ProblemType[]; + /** Structured actions the caller can take next. */ + readonly actions: readonly ActionType[]; +} /** * Serializable configured-driver report exposed through filesystem inspection. @@ -165,7 +223,22 @@ export const DriverInspectionSchema = z.object({ }).strict(); /** A validated configured-driver report. */ -export type DriverInspectionType = z.output; +export interface DriverInspectionType { + /** Stable configured driver name. */ + readonly name: string; + /** Backend family implemented by this driver. */ + readonly kind: DriverKindType; + /** Stable backend-native operations and capabilities. */ + readonly provides: readonly string[]; + /** Ownership of any long-lived backend resource. */ + readonly ownership: DriverOwnershipType; + /** Requirements already known for this configured instance. */ + readonly requirements: readonly RequirementType[]; + /** Limits with provider, policy, or probe provenance. */ + readonly limits: readonly LimitType[]; + /** Independently visible driver optimization switches. */ + readonly optimizations: readonly DriverOptimizationType[]; +} /** * Common behavior implemented by every configured storage driver. diff --git a/src/driver/file.ts b/src/driver/file.ts index 46ffcad..7c5cb59 100644 --- a/src/driver/file.ts +++ b/src/driver/file.ts @@ -48,11 +48,13 @@ export interface FileDriverWriteOptionsType extends FileDriverSignalOptionsType /** Options for a file-driver native copy. */ export interface FileDriverCopyOptionsType extends FileDriverSignalOptionsType { + /** Replaces an existing destination when true. */ readonly overwrite: boolean; } /** Options for a file-driver native move. */ export interface FileDriverMoveOptionsType extends FileDriverSignalOptionsType { + /** Replaces an existing destination when true. */ readonly overwrite: boolean; } @@ -65,7 +67,7 @@ export interface FileDriverDirectoryEntryType { } /** Portable file metadata returned by a file driver. */ -export interface FileDriverFileStatType { +interface FileDriverFileStatType { /** Portable discriminator for file metadata. */ readonly kind: "file"; /** File length in bytes. */ @@ -77,15 +79,37 @@ export interface FileDriverFileStatType { } /** Portable directory metadata returned by a file driver. */ -export interface FileDriverDirectoryStatType { +interface FileDriverDirectoryStatType { /** Portable discriminator for directory metadata. */ readonly kind: "directory"; /** Last-modified Unix epoch milliseconds when the backend can observe it. */ readonly lastModified?: number; } -/** Portable file/directory metadata returned by a file driver. */ -export type FileDriverStatType = FileDriverFileStatType | FileDriverDirectoryStatType; +/** + * Portable file or directory metadata returned by a file driver. + * + * The union stays small because callers only need the portable metadata needed + * by adapters and filesystem planning, not every runtime-specific detail from a + * host stat structure. + */ +export type FileDriverStatType = + | { + /** Portable discriminator for file metadata. */ + readonly kind: "file"; + /** File length in bytes. */ + readonly size: number; + /** Last-modified Unix epoch milliseconds. */ + readonly lastModified: number; + /** Media type, or an empty string when the backend does not know one. */ + readonly mediaType: string; + } + | { + /** Portable discriminator for directory metadata. */ + readonly kind: "directory"; + /** Last-modified Unix epoch milliseconds when the backend can observe it. */ + readonly lastModified?: number | undefined; + }; /** * Long-lived asynchronous positional file owned by a file driver. diff --git a/src/plan.ts b/src/plan.ts index b0a5c74..e8462f3 100644 --- a/src/plan.ts +++ b/src/plan.ts @@ -14,6 +14,47 @@ import { normalizePath } from "./path.ts"; import type { OptimizationType, SupportModeType } from "./schema.ts"; import { SupportModeSchema, WriteModeSchema } from "./schema.ts"; +/** Validated read preflight input after defaults are applied. */ +interface ReadPlanInputResolvedType { + readonly operation: "read"; + readonly path?: string | undefined; + readonly size?: number | undefined; + readonly range: boolean; +} + +/** Validated write preflight input after defaults are applied. */ +interface WritePlanInputResolvedType { + readonly operation: "write"; + readonly path?: string | undefined; + readonly size?: number | undefined; + readonly inputBytes?: number | undefined; + readonly source: WriteSourceType; + readonly mode: "replace" | "append" | "update"; +} + +/** Validated copy preflight input. */ +interface CopyPlanInputResolvedType { + readonly operation: "copy"; + readonly path?: string | undefined; + readonly destination?: string | undefined; + readonly size?: number | undefined; +} + +/** Validated move preflight input. */ +interface MovePlanInputResolvedType { + readonly operation: "move"; + readonly path?: string | undefined; + readonly destination?: string | undefined; + readonly size?: number | undefined; +} + +/** Validated preflight input shape after schema defaults are applied. */ +type ResolvedPlanInputType = + | ReadPlanInputResolvedType + | WritePlanInputResolvedType + | CopyPlanInputResolvedType + | MovePlanInputResolvedType; + /** * Physical source form supplied to a planned write. * @@ -22,7 +63,7 @@ import { SupportModeSchema, WriteModeSchema } from "./schema.ts"; */ export const WriteSourceSchema = z.enum(["bytes", "stream"]); /** Validated physical write-source form. */ -export type WriteSourceType = z.output; +export type WriteSourceType = "bytes" | "stream"; /** * Filesystem operations supported by deterministic preflight planning. * @@ -31,7 +72,59 @@ export type WriteSourceType = z.output; */ export const PlanOperationSchema = z.enum(["read", "write", "copy", "move"]); /** Validated preflight operation name. */ -export type PlanOperationType = z.output; +export type PlanOperationType = "read" | "write" | "copy" | "move"; + +/** Preflight input for a read request before schema defaults are applied. */ +export interface ReadPlanInputType { + /** Selects a read preflight request. */ + readonly operation: "read"; + /** Path the caller plans to read. */ + readonly path?: string | undefined; + /** Caller-known logical size when available. */ + readonly size?: number | undefined; + /** Whether the read plans a byte range instead of the full file. */ + readonly range?: boolean | undefined; +} + +/** Preflight input for a write request before schema defaults are applied. */ +export interface WritePlanInputType { + /** Selects a write preflight request. */ + readonly operation: "write"; + /** Path the caller plans to write. */ + readonly path?: string | undefined; + /** Caller-known logical size when available. */ + readonly size?: number | undefined; + /** Caller-known already-buffered byte count when streaming. */ + readonly inputBytes?: number | undefined; + /** Physical source form for the write request. */ + readonly source: WriteSourceType; + /** Requested write semantics. */ + readonly mode?: "replace" | "append" | "update" | undefined; +} + +/** Preflight input for a copy request. */ +export interface CopyPlanInputType { + /** Selects a copy preflight request. */ + readonly operation: "copy"; + /** Source path the caller plans to copy. */ + readonly path?: string | undefined; + /** Destination path for the copy request. */ + readonly destination?: string | undefined; + /** Caller-known logical size when available. */ + readonly size?: number | undefined; +} + +/** Preflight input for a move request. */ +export interface MovePlanInputType { + /** Selects a move preflight request. */ + readonly operation: "move"; + /** Source path the caller plans to move. */ + readonly path?: string | undefined; + /** Destination path for the move request. */ + readonly destination?: string | undefined; + /** Caller-known logical size when available. */ + readonly size?: number | undefined; +} /** * Serializable preflight request for one concrete filesystem operation. @@ -69,7 +162,7 @@ export const PlanInputSchema = z.discriminatedUnion("operation", [ }).strict(), ]); /** Input accepted by filesystem preflight before defaults and path normalization. */ -export type PlanInputType = z.input; +export type PlanInputType = ReadPlanInputType | WritePlanInputType | CopyPlanInputType | MovePlanInputType; /** * Structured preflight result for the complete driver -> adapter -> filesystem stack. @@ -90,7 +183,26 @@ export const PlanSchema = z.object({ actions: z.array(ActionSchema).readonly(), }).strict(); /** Validated complete-stack preflight result. */ -export type PlanType = z.output; +export interface PlanType { + /** Filesystem operation that was planned. */ + readonly operation: PlanOperationType; + /** Whether the complete storage stack can perform the request safely. */ + readonly supported: boolean; + /** Effective support mode after driver, adapter, and facade policy are combined. */ + readonly support: SupportModeType; + /** Backend-native planning result preserved inside the full plan. */ + readonly driver: DriverPlanType; + /** Facade-owned buffering required before the request can proceed. */ + readonly bufferBytes?: number | undefined; + /** Physical part or block size when partitioning is involved. */ + readonly partBytes?: number | undefined; + /** Physical part or block count when partitioning is involved. */ + readonly parts?: number | undefined; + /** Structured problems found across the complete storage stack. */ + readonly problems: readonly ProblemType[]; + /** Structured actions the caller can take next. */ + readonly actions: readonly ActionType[]; +} /** * Internal facade state required to combine adapter and driver preflight. @@ -131,7 +243,7 @@ function action(kind: ActionType["kind"], detail?: string): ActionType { * paths are normalized, defaults are resolved, and only driver-relevant fields * cross the boundary. */ -function getDriverPlan(input: z.output, adapter: AdapterType): DriverPlanType { +function getDriverPlan(input: ResolvedPlanInputType, adapter: AdapterType): DriverPlanType { return adapter.driver.plan({ operation: input.operation, ...(input.path === undefined ? {} : { path: normalizePath(input.path) }), diff --git a/src/schema.ts b/src/schema.ts index d63b7c9..7bf87dc 100644 --- a/src/schema.ts +++ b/src/schema.ts @@ -21,7 +21,7 @@ export const PathSchema = z.string().refine( ); /** A validated canonical virtual filesystem path. */ -export type PathType = z.output; +export type PathType = string; /** Stable non-empty diagnostic name assigned to one adapter implementation. */ export const AdapterNameSchema = z.string().min(1); @@ -38,7 +38,7 @@ export type AdapterNameType = z.output; export const EntryKindSchema = z.enum(["file", "directory"]); /** A validated filesystem entry kind. */ -export type EntryKindType = z.output; +export type EntryKindType = "file" | "directory"; /** * Execution contexts that can host browser storage access. @@ -58,7 +58,13 @@ export const OpfsContextSchema = z.enum([ ]); /** A validated browser execution context classification. */ -export type OpfsContextType = z.output; +export type OpfsContextType = + | "window" + | "dedicated-worker" + | "shared-worker" + | "service-worker" + | "worker" + | "unknown"; /** * Mutation coordination policies supported by {@link createFileSystem}. @@ -70,7 +76,7 @@ export type OpfsContextType = z.output; export const CoordinationModeSchema = z.enum(["auto", "web-locks", "local", "none"]); /** A validated mutation coordination policy. */ -export type CoordinationModeType = z.output; +export type CoordinationModeType = "auto" | "web-locks" | "local" | "none"; /** * Write modes shared by the facade and adapters. @@ -81,7 +87,7 @@ export type CoordinationModeType = z.output; export const WriteModeSchema = z.enum(["replace", "append", "update"]); /** A validated file write mode. */ -export type WriteModeType = z.output; +export type WriteModeType = "replace" | "append" | "update"; /** * How one operation is provided by the selected storage stack. @@ -95,7 +101,7 @@ export type WriteModeType = z.output; export const SupportModeSchema = z.enum(["native", "emulated", "partitioned", "unsupported"]); /** A validated storage support mode. */ -export type SupportModeType = z.output; +export type SupportModeType = "native" | "emulated" | "partitioned" | "unsupported"; /** * Metrics collection cost selected for one filesystem or protocol client. @@ -107,7 +113,7 @@ export type SupportModeType = z.output; export const MetricsModeSchema = z.enum(["none", "basic", "timing"]); /** A validated metrics collection mode. */ -export type MetricsModeType = z.output; +export type MetricsModeType = "none" | "basic" | "timing"; /** * Physical partition policy for backends with a smaller value limit than the @@ -116,7 +122,7 @@ export type MetricsModeType = z.output; export const PartitionModeSchema = z.enum(["never", "auto", "always"]); /** A validated physical partition policy. */ -export type PartitionModeType = z.output; +export type PartitionModeType = "never" | "auto" | "always"; /** * Inspectable physical layout used when one logical file spans provider values. @@ -136,7 +142,20 @@ export const AdapterPartitionSchema = z.object({ }).strict(); /** A validated physical partition layout. */ -export type AdapterPartitionType = z.output; +export interface AdapterPartitionType { + /** Partitioning policy selected for this adapter. */ + readonly mode: PartitionModeType; + /** Physical part or block size used by the layout. */ + readonly partBytes: number; + /** Logical size where `auto` starts partitioning when known. */ + readonly thresholdBytes?: number | undefined; + /** Whether streamed writes already use the partitioned layout. */ + readonly stream?: boolean | undefined; + /** Maximum physical part or block count when known. */ + readonly maxParts?: number | undefined; + /** Stable name of the physical layout strategy. */ + readonly layout: string; +} /** * Optional backend limits that can be inspected before work begins. @@ -165,7 +184,24 @@ export const AdapterLimitsSchema = z.object({ }).strict(); /** Portable hard limits known by one configured adapter. */ -export type AdapterLimitsType = z.output; +export interface AdapterLimitsType { + /** Maximum logical file size accepted by this configured adapter. */ + readonly maxFileBytes?: number | undefined; + /** Maximum materialized backend value size when the backend has one. */ + readonly maxValueBytes?: number | undefined; + /** Maximum serialized key size when the backend has one. */ + readonly maxKeyBytes?: number | undefined; + /** Minimum legal provider part or block size. */ + readonly minPartBytes?: number | undefined; + /** Maximum legal provider part or block size. */ + readonly maxPartBytes?: number | undefined; + /** Maximum provider part or block count for one logical object. */ + readonly maxParts?: number | undefined; + /** Maximum useful concurrency known by this adapter. */ + readonly maxConcurrency?: number | undefined; + /** Maximum bytes allowed in one batched or transactional mutation. */ + readonly maxBatchBytes?: number | undefined; +} /** * Performance routes that the filesystem facade can deliberately bypass. @@ -188,7 +224,18 @@ export const OptimizationSchema = z.object({ }).strict(); /** Resolved performance-route policy for one filesystem facade. */ -export type OptimizationType = z.output; +export interface OptimizationType { + /** Enables adapter-native streaming reads when available. */ + readonly streamRead: boolean; + /** Enables adapter-native streaming writes when available. */ + readonly streamWrite: boolean; + /** Enables native range reads when available. */ + readonly rangeRead: boolean; + /** Enables adapter-native or server-side copy routes when available. */ + readonly nativeCopy: boolean; + /** Enables adapter-native move or rename routes when available. */ + readonly nativeMove: boolean; +} /** * Stable adapter capability description. @@ -222,7 +269,26 @@ export const AdapterCapabilitiesSchema = z.object({ }); /** Native operations implemented by one adapter. */ -export type AdapterCapabilitiesType = z.output; +export interface AdapterCapabilitiesType { + /** Adapter can materialize file bytes through `readFile()`. */ + readonly read: boolean; + /** Adapter can commit materialized file bytes through `writeFile()`. */ + readonly write: boolean; + /** Adapter can open a native read stream. */ + readonly streamRead: boolean; + /** Write modes that `writeStream()` can perform natively. */ + readonly streamWriteModes: readonly WriteModeType[]; + /** Adapter can satisfy byte ranges without whole-file materialization. */ + readonly rangeRead: boolean; + /** Adapter can copy bytes without routing them through the facade. */ + readonly nativeCopy: boolean; + /** Adapter can move or rename through one backend-native route. */ + readonly nativeMove: boolean; + /** Adapter exposes a long-lived asynchronous positional writer. */ + readonly positionalWrite: boolean; + /** Adapter exposes a synchronous random-access file resource. */ + readonly syncAccess: boolean; +} /** * Stable error categories exposed by the package. @@ -248,7 +314,20 @@ export const ErrorCodeSchema = z.enum([ ]); /** A validated package error category. */ -export type ErrorCodeType = z.output; +export type ErrorCodeType = + | "unavailable" + | "not-found" + | "already-exists" + | "type-mismatch" + | "invalid-path" + | "invalid-operation" + | "not-supported" + | "locked" + | "quota-exceeded" + | "permission-denied" + | "aborted" + | "too-large" + | "unknown"; /** Version stored with record-backed filesystem entries. */ export const RecordVersionSchema = z.literal(1); @@ -328,25 +407,25 @@ export type SqlIdentifierType = z.output; export const DriverKindSchema = z.enum(["file", "record", "object"]); /** A validated backend driver family. */ -export type DriverKindType = z.output; +export type DriverKindType = "file" | "record" | "object"; /** Why one driver limit exists. */ export const LimitKindSchema = z.enum(["hard", "policy", "dynamic"]); /** A validated limit kind. */ -export type LimitKindType = z.output; +export type LimitKindType = "hard" | "policy" | "dynamic"; /** Layer that supplied one limit value. */ export const LimitSourceSchema = z.enum(["provider", "implementation", "user", "probe"]); /** A validated limit source. */ -export type LimitSourceType = z.output; +export type LimitSourceType = "provider" | "implementation" | "user" | "probe"; /** Unit used by one numeric limit. */ export const LimitUnitSchema = z.enum(["bytes", "count", "milliseconds", "operations"]); /** A validated limit unit. */ -export type LimitUnitType = z.output; +export type LimitUnitType = "bytes" | "count" | "milliseconds" | "operations"; /** * One inspectable storage limit with explicit provenance. @@ -369,13 +448,26 @@ export const LimitSchema = z.object({ }); /** A validated storage limit. */ -export type LimitType = z.output; +export interface LimitType { + /** Stable machine-readable limit code. */ + readonly code: string; + /** Whether the limit is hard, policy-driven, or dynamic. */ + readonly kind: LimitKindType; + /** Layer that supplied the limit value. */ + readonly source: LimitSourceType; + /** Unit used by the numeric value. */ + readonly unit: LimitUnitType; + /** Current numeric limit when known. */ + readonly value?: number | undefined; + /** Human-readable context for diagnostics. */ + readonly detail?: string | undefined; +} /** Current state of one driver requirement. */ export const RequirementStateSchema = z.enum(["available", "missing", "unknown"]); /** A validated requirement state. */ -export type RequirementStateType = z.output; +export type RequirementStateType = "available" | "missing" | "unknown"; /** * One runtime, provider, permission, or configuration requirement. @@ -394,13 +486,20 @@ export const RequirementSchema = z.object({ }); /** A validated driver requirement. */ -export type RequirementType = z.output; +export interface RequirementType { + /** Stable machine-readable requirement code. */ + readonly code: string; + /** Current known availability state. */ + readonly state: RequirementStateType; + /** Concrete reason when the requirement is missing. */ + readonly reason?: string | undefined; +} /** Ownership state for one configured driver backend resource. */ export const DriverOwnershipSchema = z.enum(["none", "borrowed", "owned"]); /** A validated configured-driver backend ownership state. */ -export type DriverOwnershipType = z.output; +export type DriverOwnershipType = "none" | "borrowed" | "owned"; /** * One independently controllable driver optimization. @@ -422,4 +521,15 @@ export const DriverOptimizationSchema = z.object({ }); /** A validated driver optimization declaration. */ -export type DriverOptimizationType = z.output; +export interface DriverOptimizationType { + /** Stable machine-readable optimization code. */ + readonly code: string; + /** Current enabled state. */ + readonly enabled: boolean; + /** Whether this optimization changes observable behavior. */ + readonly changesBehavior: boolean; + /** Whether callers can turn this optimization off. */ + readonly disableable: boolean; + /** Human-readable detail for diagnostics or documentation. */ + readonly detail?: string | undefined; +} -- 2.51.2