@danypops/vehicle-core 0.18.0 → 0.18.1

package/dist/schemas/index.d.ts

@@ -2,3 +2,4 @@ export * from "./codec.js";
 export * from "./json.js";
 export * from "./loose-object.js";
 export * from "./presentation.js";
+export * from "./primitives.js";

package/dist/schemas/index.js

@@ -2,3 +2,4 @@ export * from "./codec.js";
 export * from "./json.js";
 export * from "./loose-object.js";
 export * from "./presentation.js";
+export * from "./primitives.js";

package/dist/schemas/primitives.d.ts

@@ -0,0 +1,37 @@
+import type { VehicleSchemaIssue } from "./codec.js";
+/** The `{ success: false, issues }` half of VehicleSchemaResult -- named on its own since every hand-written safeParse's failure branch is this exact shape, never a bare Error. */
+export interface VehicleSchemaFailure {
+    readonly success: false;
+    readonly issues: readonly VehicleSchemaIssue[];
+}
+/**
+ * A safeParse's own first, universal check: the value wasn't even an object. Every hand-written
+ * object-shaped VehicleSchemaCodec across the ecosystem re-derived this exact literal before this
+ * existed as a shared primitive -- one canonical wording now, not five near-identical copies.
+ */
+export declare function notAnObjectIssue(): VehicleSchemaFailure;
+/**
+ * One field-scoped failure. `path` accepts a single key (the common case: a top-level field) or
+ * a full path segment array (for a nested/array-indexed field, matching VehicleSchemaIssue.path's
+ * own `readonly (string | number)[]` shape directly) -- both real shapes existing hand-written
+ * safeParse implementations across the ecosystem already needed.
+ */
+export declare function schemaIssue(path: string | number | readonly (string | number)[], message: string): VehicleSchemaFailure;
+/** True for a real object value -- not null, not an array (JSON Schema's own object/array distinction; `typeof [] === "object"` is not what a caller checking "is this a plain object" means). */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/** A non-empty string -- the shape every identifier-like field (workspaceId, ref, path, ...) across the ecosystem actually requires; an empty string is a real, distinct failure from "not a string at all". */
+export declare function isNonEmptyString(value: unknown): value is string;
+/** A real integer safely representable in a double -- the base every bounded-count/size field below builds on. */
+export declare function isSafeInteger(value: unknown): value is number;
+/** A safe integer that is zero or more -- e.g. an offset/cursor field where zero is a real, valid value, unlike a positive-only count. */
+export declare function isNonNegativeSafeInteger(value: unknown): value is number;
+/**
+ * A safe integer that is at least 1 -- the shape every bounded-count/size field (maxBytes,
+ * maxCount, maxResults, maxMatches, ...) across the ecosystem actually requires. `maximum`, when
+ * given, additionally caps the accepted value inclusively -- a field that must be positive AND
+ * never exceed some hard ceiling (e.g. a page size capped well below an unbounded read) is a real,
+ * recurring combination, not a hypothetical one.
+ */
+export declare function isPositiveSafeInteger(value: unknown, maximum?: number): value is number;
+/** An array whose every element is a string -- the shape every string-list field (labels, tags, pathspecs, ...) across the ecosystem actually requires; a mixed-type array is a real, distinct failure from "not an array at all". */
+export declare function isStringArray(value: unknown): value is string[];

package/dist/schemas/primitives.js

@@ -0,0 +1,47 @@
+/**
+ * A safeParse's own first, universal check: the value wasn't even an object. Every hand-written
+ * object-shaped VehicleSchemaCodec across the ecosystem re-derived this exact literal before this
+ * existed as a shared primitive -- one canonical wording now, not five near-identical copies.
+ */
+export function notAnObjectIssue() {
+    return { success: false, issues: [{ path: [], message: "input must be an object" }] };
+}
+/**
+ * One field-scoped failure. `path` accepts a single key (the common case: a top-level field) or
+ * a full path segment array (for a nested/array-indexed field, matching VehicleSchemaIssue.path's
+ * own `readonly (string | number)[]` shape directly) -- both real shapes existing hand-written
+ * safeParse implementations across the ecosystem already needed.
+ */
+export function schemaIssue(path, message) {
+    return { success: false, issues: [{ path: Array.isArray(path) ? path : [path], message }] };
+}
+/** True for a real object value -- not null, not an array (JSON Schema's own object/array distinction; `typeof [] === "object"` is not what a caller checking "is this a plain object" means). */
+export function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** A non-empty string -- the shape every identifier-like field (workspaceId, ref, path, ...) across the ecosystem actually requires; an empty string is a real, distinct failure from "not a string at all". */
+export function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+/** A real integer safely representable in a double -- the base every bounded-count/size field below builds on. */
+export function isSafeInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value);
+}
+/** A safe integer that is zero or more -- e.g. an offset/cursor field where zero is a real, valid value, unlike a positive-only count. */
+export function isNonNegativeSafeInteger(value) {
+    return isSafeInteger(value) && value >= 0;
+}
+/**
+ * A safe integer that is at least 1 -- the shape every bounded-count/size field (maxBytes,
+ * maxCount, maxResults, maxMatches, ...) across the ecosystem actually requires. `maximum`, when
+ * given, additionally caps the accepted value inclusively -- a field that must be positive AND
+ * never exceed some hard ceiling (e.g. a page size capped well below an unbounded read) is a real,
+ * recurring combination, not a hypothetical one.
+ */
+export function isPositiveSafeInteger(value, maximum) {
+    return isSafeInteger(value) && value >= 1 && (maximum === undefined || value <= maximum);
+}
+/** An array whose every element is a string -- the shape every string-list field (labels, tags, pathspecs, ...) across the ecosystem actually requires; a mixed-type array is a real, distinct failure from "not an array at all". */
+export function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/vehicle-core",
-	"version": "0.18.0",
+	"version": "0.18.1",
 	"description": "Vehicle's runtime-neutral wire contract: operation descriptors, schema codecs, failure shapes. Zero runtime dependencies, zero Bun-specific code -- the one thing every Vehicle client and server package depends on.",
 	"license": "MIT",
 	"type": "module",

package/src/schemas/index.ts

@@ -2,3 +2,4 @@ export * from "./codec.js";
 export * from "./json.js";
 export * from "./loose-object.js";
 export * from "./presentation.js";
+export * from "./primitives.js";

package/src/schemas/primitives.ts

@@ -0,0 +1,62 @@
+import type { VehicleSchemaIssue } from "./codec.js";
+
+/** The `{ success: false, issues }` half of VehicleSchemaResult -- named on its own since every hand-written safeParse's failure branch is this exact shape, never a bare Error. */
+export interface VehicleSchemaFailure {
+	readonly success: false;
+	readonly issues: readonly VehicleSchemaIssue[];
+}
+
+/**
+ * A safeParse's own first, universal check: the value wasn't even an object. Every hand-written
+ * object-shaped VehicleSchemaCodec across the ecosystem re-derived this exact literal before this
+ * existed as a shared primitive -- one canonical wording now, not five near-identical copies.
+ */
+export function notAnObjectIssue(): VehicleSchemaFailure {
+	return { success: false, issues: [{ path: [], message: "input must be an object" }] };
+}
+
+/**
+ * One field-scoped failure. `path` accepts a single key (the common case: a top-level field) or
+ * a full path segment array (for a nested/array-indexed field, matching VehicleSchemaIssue.path's
+ * own `readonly (string | number)[]` shape directly) -- both real shapes existing hand-written
+ * safeParse implementations across the ecosystem already needed.
+ */
+export function schemaIssue(path: string | number | readonly (string | number)[], message: string): VehicleSchemaFailure {
+	return { success: false, issues: [{ path: Array.isArray(path) ? path : [path], message }] };
+}
+
+/** True for a real object value -- not null, not an array (JSON Schema's own object/array distinction; `typeof [] === "object"` is not what a caller checking "is this a plain object" means). */
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** A non-empty string -- the shape every identifier-like field (workspaceId, ref, path, ...) across the ecosystem actually requires; an empty string is a real, distinct failure from "not a string at all". */
+export function isNonEmptyString(value: unknown): value is string {
+	return typeof value === "string" && value.length > 0;
+}
+
+/** A real integer safely representable in a double -- the base every bounded-count/size field below builds on. */
+export function isSafeInteger(value: unknown): value is number {
+	return typeof value === "number" && Number.isSafeInteger(value);
+}
+
+/** A safe integer that is zero or more -- e.g. an offset/cursor field where zero is a real, valid value, unlike a positive-only count. */
+export function isNonNegativeSafeInteger(value: unknown): value is number {
+	return isSafeInteger(value) && value >= 0;
+}
+
+/**
+ * A safe integer that is at least 1 -- the shape every bounded-count/size field (maxBytes,
+ * maxCount, maxResults, maxMatches, ...) across the ecosystem actually requires. `maximum`, when
+ * given, additionally caps the accepted value inclusively -- a field that must be positive AND
+ * never exceed some hard ceiling (e.g. a page size capped well below an unbounded read) is a real,
+ * recurring combination, not a hypothetical one.
+ */
+export function isPositiveSafeInteger(value: unknown, maximum?: number): value is number {
+	return isSafeInteger(value) && value >= 1 && (maximum === undefined || value <= maximum);
+}
+
+/** An array whose every element is a string -- the shape every string-list field (labels, tags, pathspecs, ...) across the ecosystem actually requires; a mixed-type array is a real, distinct failure from "not an array at all". */
+export function isStringArray(value: unknown): value is string[] {
+	return Array.isArray(value) && value.every((item) => typeof item === "string");
+}