@marcelsud/keel.ts 0.1.0 → 0.2.0

package/README.md

@@ -16,7 +16,7 @@ Or with Bun:
 bun add @marcelsud/keel.ts
 ```
 
-You need a running Keel environment. For the standalone storage example below, install the [Keel CLI](https://github.com/marcelsud/keel#install-the-cli) and run `keel` in another terminal first. To run a service with `keel dev`, configure its startup command in `keel.json`, for example `{ "command": ["bun", "run", "main.ts"] }`.
+You need a running Keel environment. For the standalone storage example below, install the [Keel CLI](https://github.com/marcelsud/keel#install-the-cli) and run `keel` in another terminal first. To run a service with `keel dev`, configure its startup command in `keel.json`, for example `{ "command": ["bun", "run", "service.ts"] }`. The [first-service walkthrough](https://github.com/marcelsud/keel#start-a-service) describes the new `keel init` flow and its CLI version requirements; protobuf is optional for JSON actions, storage, events, and jobs.
 
 ## Connect and store data
 
@@ -37,6 +37,31 @@ try {
 }
 ```
 
+## Validate an action
+
+The schema helpers require SDK 0.2.0 or later. Before `app.start()`, declare an action on your connected app:
+
+```ts
+const createNote = app.action({
+  name: "createNote",
+  args: app.schema.object({
+    body: app.schema.string(),
+    labels: app.schema.string().array().optional(),
+  }),
+  async handler(ctx, input) {
+    const id = await ctx.collection.insert("notes", input);
+    return { id, body: input.body };
+  },
+});
+
+// After app.start():
+const note = await createNote({ body: "Hello" });
+```
+
+The SDK infers the handler input and action result. Missing or invalid fields return a 400 service error before the handler runs. Objects validate declared fields and strip extra fields; strings are checked without coercion or trimming.
+
+Use `string()`, `number()`, `integer()`, `boolean()`, `object()`, `array()`, `record()`, `enum()`, `literal()`, `union()`, `null()`, and `unknown()`, with `.optional()` and `.nullable()` to compose shapes. You can also import `schema` and `type Infer` directly from the package, or continue supplying your own `args.parse()` parser. These helpers validate JSON actions; protobuf contracts remain the way to share generated API types across languages.
+
 ## Call a typed service
 
 Install the [Keel CLI](https://github.com/marcelsud/keel#install-the-cli). Its release bundle includes the generators; TypeScript generation uses your Node.js runtime.

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 import { type NatsConnection } from "@nats-io/transport-node";
 import { ServiceError } from "@nats-io/services";
 import type { DescService } from "@bufbuild/protobuf";
+import { schema, ValidationError } from "./schema.js";
 import { type Contract, type ContractOptions, type Schema, type ServiceClient, type ServiceImplementation } from "./protobuf.js";
-export { ServiceError };
+export { ServiceError, schema, ValidationError };
+export type { Infer, Validator } from "./schema.js";
 export type { Contract, ContractOptions, ContractState, Schema, ServiceClient, ServiceImplementation } from "./protobuf.js";
-export declare class ValidationError extends Error {
-}
 export interface Options {
     url?: string;
     name: string;
@@ -49,6 +49,24 @@ export interface HandlerContext {
 export declare class Keel implements HandlerContext {
     private nc;
     private options;
+    readonly schema: {
+        string: () => import("./schema.js").Validator<string, false>;
+        boolean: () => import("./schema.js").Validator<boolean, false>;
+        number: () => import("./schema.js").Validator<number, false>;
+        integer: () => import("./schema.js").Validator<number, false>;
+        null: () => import("./schema.js").Validator<null, false>;
+        unknown: () => import("./schema.js").Validator<unknown, false>;
+        any: () => import("./schema.js").Validator<unknown, false>;
+        object<S extends {
+            [x: string]: import("./schema.js").Validator<unknown, boolean>;
+        }>(shape: S): import("./schema.js").Validator<{ [K_1 in Exclude<keyof S, { [K in keyof S]: S[K]["isOptional"] extends true ? K : never; }[keyof S]>]: import("./schema.js").Infer<S[K_1]>; } & { [K_2 in { [K in keyof S]: S[K]["isOptional"] extends true ? K : never; }[keyof S]]?: import("./schema.js").Infer<S[K_2]> | undefined; }, false>;
+        array<T>(item: import("./schema.js").Validator<T>): import("./schema.js").Validator<T[], false>;
+        optional<T>(item: import("./schema.js").Validator<T>): import("./schema.js").Validator<T | undefined, true>;
+        record<T>(item: import("./schema.js").Validator<T>): import("./schema.js").Validator<Record<string, T>, false>;
+        literal<const T extends string | number | boolean | null>(expected: T): import("./schema.js").Validator<T, false>;
+        enum<const Values extends readonly [string, ...string[]]>(values: Values): import("./schema.js").Validator<Values[number], false>;
+        union<const V extends readonly [import("./schema.js").Validator, ...import("./schema.js").Validator[]]>(...members: V): import("./schema.js").Validator<import("./schema.js").Infer<V[number]>, false>;
+    };
     readonly kv: KV;
     readonly collection: Collections;
     readonly pubsub: HandlerContext["pubsub"];

package/dist/index.js

@@ -1,12 +1,11 @@
 import { connect } from "@nats-io/transport-node";
 import { ServiceError, Svcm } from "@nats-io/services";
 import { jetstream } from "@nats-io/jetstream";
+import { schema, ValidationError } from "./schema.js";
 import { protobufClient, schemaSubject, serviceEndpoints, validateSchema, } from "./protobuf.js";
-export { ServiceError };
+export { ServiceError, schema, ValidationError };
 const prefix = "keel.v1";
 const identifier = /^[a-zA-Z0-9_-]+$/;
-export class ValidationError extends Error {
-}
 function name(value) {
     if (!identifier.test(value))
         throw new ValidationError("invalid service or action name");
@@ -65,6 +64,7 @@ export class Collections {
 export class Keel {
     nc;
     options;
+    schema = schema;
     kv;
     collection;
     pubsub;

package/dist/schema.d.ts

@@ -0,0 +1,36 @@
+export declare class ValidationError extends Error {
+}
+export interface Validator<T = unknown, Optional extends boolean = boolean> {
+    readonly isOptional: Optional;
+    parse(value: unknown, path?: string): T;
+    array(): Validator<T[], false>;
+    nullable(): Validator<T | null, Optional>;
+    optional(): Validator<T | undefined, true>;
+}
+export type Infer<V extends Validator> = V extends Validator<infer T> ? T : never;
+type Shape = Record<string, Validator>;
+type OptionalKeys<S extends Shape> = {
+    [K in keyof S]: S[K]["isOptional"] extends true ? K : never;
+}[keyof S];
+type ObjectValue<S extends Shape> = {
+    [K in Exclude<keyof S, OptionalKeys<S>>]: Infer<S[K]>;
+} & {
+    [K in OptionalKeys<S>]?: Infer<S[K]>;
+};
+export declare const schema: {
+    string: () => Validator<string, false>;
+    boolean: () => Validator<boolean, false>;
+    number: () => Validator<number, false>;
+    integer: () => Validator<number, false>;
+    null: () => Validator<null, false>;
+    unknown: () => Validator<unknown, false>;
+    any: () => Validator<unknown, false>;
+    object<S extends Shape>(shape: S): Validator<ObjectValue<S>, false>;
+    array<T>(item: Validator<T>): Validator<T[], false>;
+    optional<T>(item: Validator<T>): Validator<T | undefined, true>;
+    record<T>(item: Validator<T>): Validator<Record<string, T>, false>;
+    literal<const T extends string | number | boolean | null>(expected: T): Validator<T, false>;
+    enum<const Values extends readonly [string, ...string[]]>(values: Values): Validator<Values[number], false>;
+    union<const V extends readonly [Validator, ...Validator[]]>(...members: V): Validator<Infer<V[number]>, false>;
+};
+export {};

package/dist/schema.js

@@ -0,0 +1,87 @@
+export class ValidationError extends Error {
+}
+function validator(parse, isOptional) {
+    return {
+        isOptional,
+        parse: (value, path = "value") => parse(value, path),
+        array() {
+            return validator((value, path) => {
+                if (!Array.isArray(value))
+                    throw new ValidationError(`${path} must be an array`);
+                return value.map((item, index) => parse(item, `${path}[${index}]`));
+            }, false);
+        },
+        nullable() {
+            return validator((value, path) => value === null ? null : parse(value, path), isOptional);
+        },
+        optional() {
+            return validator((value, path) => value === undefined ? undefined : parse(value, path), true);
+        },
+    };
+}
+function scalar(type, accepts) {
+    return validator((value, path) => {
+        if (!accepts(value))
+            throw new ValidationError(`${path} must be ${type}`);
+        return value;
+    }, false);
+}
+function object(value, path) {
+    if (typeof value !== "object" || value === null ||
+        ![Object.prototype, null].includes(Object.getPrototypeOf(value))) {
+        throw new ValidationError(`${path} must be an object`);
+    }
+    return value;
+}
+const unknown = () => validator((value) => value, false);
+export const schema = {
+    string: () => scalar("a string", (value) => typeof value === "string"),
+    boolean: () => scalar("a boolean", (value) => typeof value === "boolean"),
+    number: () => scalar("a finite number", (value) => typeof value === "number" && Number.isFinite(value)),
+    integer: () => scalar("a safe integer", (value) => typeof value === "number" && Number.isSafeInteger(value)),
+    null: () => scalar("null", (value) => value === null),
+    unknown,
+    any: unknown,
+    object(shape) {
+        return validator((value, path) => {
+            const input = object(value, path);
+            return Object.fromEntries(Object.entries(shape).flatMap(([key, field]) => {
+                if (!Object.hasOwn(input, key)) {
+                    if (field.isOptional)
+                        return [];
+                    throw new ValidationError(`${path}.${key} is required`);
+                }
+                return [[key, field.parse(input[key], `${path}.${key}`)]];
+            }));
+        }, false);
+    },
+    array(item) {
+        return item.array();
+    },
+    optional(item) {
+        return item.optional();
+    },
+    record(item) {
+        return validator((value, path) => Object.fromEntries(Object.entries(object(value, path)).map(([key, entry]) => [key, item.parse(entry, `${path}.${key}`)])), false);
+    },
+    literal(expected) {
+        return scalar(JSON.stringify(expected), (value) => value === expected);
+    },
+    enum(values) {
+        return scalar(`one of ${values.join(", ")}`, (value) => typeof value === "string" && values.includes(value));
+    },
+    union(...members) {
+        return validator((value, path) => {
+            let firstError;
+            for (const member of members) {
+                try {
+                    return member.parse(value, path);
+                }
+                catch (error) {
+                    firstError ??= error;
+                }
+            }
+            throw firstError;
+        }, false);
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marcelsud/keel.ts",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "TypeScript SDK for Keel services, typed clients, storage, events, and background jobs.",
   "license": "MIT",
   "type": "module",