@jakobkg/shapes-ts 0.1.0

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2025 Jakob Grønhaug.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+    1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+    2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+    3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,3 @@
+# shapes-ts
+
+Toy library to create runtime safe types in TS, see `main.ts` for example usage

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * as Shapes from "./shapes";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/shapes/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Shapes = void 0;
+exports.Shapes = require("./shapes");

package/dist/shapes.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Bridge to convert a Shape into a TS type.
+ */
+export type Type<T extends Shape> = T["primitive"];
+type ShapePredicate<T> = (x: T) => boolean;
+interface Shape<T = any> {
+    readonly typename: string;
+    readonly primitive: T;
+    readonly optional?: boolean;
+    readonly predicates: ShapePredicate<T>[];
+    check(x: unknown): x is T;
+    /**
+     * Adds a custom validation predicate to the shape
+     * @param predicate A function that takes a value of the shape's type and returns a boolean
+     * @param description Optional description of the constraint for error messages
+     * @returns A new shape with the additional validation
+     */
+    where(predicate: ShapePredicate<T>, description: string): Shape<T>;
+    and<U>(other: Shape<U>): IntersectionShape<T, U>;
+    or<U>(other: Shape<U>): UnionShape<T, U>;
+}
+interface ObjectShape<T = Record<string, unknown>> extends Shape<T> {
+    readonly properties: Record<string, Shape<T>>;
+    readonly allowUnknownProperties?: boolean;
+}
+interface ObjectShapeOptions {
+    readonly allowUnknownProperties?: boolean;
+    readonly additionalPermittedProperties?: Record<string, Shape<Record<string, unknown>>>;
+}
+interface ArrayShape<T extends Shape> extends Shape<Array<T["primitive"]>> {
+    readonly inner: T;
+}
+interface UnionShape<Left, Right> extends Shape<Left | Right> {
+    left: Shape<Left>;
+    right: Shape<Right>;
+}
+interface IntersectionShape<Left, Right> extends Shape<Left & Right> {
+    left: Shape<Left>;
+    right: Shape<Right>;
+}
+interface OptionalShape<T extends Shape> extends Shape<T["primitive"] | undefined> {
+    readonly inner: T;
+}
+interface NullableShape<T extends Shape> extends Shape<T["primitive"] | null> {
+    readonly inner: T;
+}
+/**
+ * Creates a shape representing a JS `number`.
+ * Does not support BigInt.
+ */
+export declare function number(): Shape<number>;
+/**
+ * Creates a shape representing a JS `string`.
+ */
+export declare function string(): Shape<string>;
+/**
+ * Creates a shape representing a JS `boolean`.
+ */
+export declare function boolean(): Shape<boolean>;
+/**
+ * Creates an array shape, representing `Array<T>` (aka `T[]`).
+ * Takes the shape representing `T` as a parameter.
+ */
+export declare function array<T extends Shape>(shape: T): ArrayShape<T>;
+/**
+ * Creates an object shape.
+ *
+ * @example
+ * const Group = Shapes.object({
+ *  id: Shapes.number(),
+ *  name: Shapes.string(),
+ * });
+ *
+ * const User = Shapes.object({
+ *  id: Shapes.number(),
+ *  name: Shapes.string(),
+ *  groups: Shapes.nullable(
+ *    Shapes.array(Group)
+ *   )
+ * });
+ */
+export declare function object<T extends Record<string, Shape>>(properties: T, options?: ObjectShapeOptions): ObjectShape<{
+    [K in keyof T]: Type<T[K]>;
+}>;
+/**
+ * Creates a shape representing an optional type.
+ * `Shapes.optional(T)` corresponds to `T | undefined`
+ */
+export declare function optional<T extends Shape>(shape: T): OptionalShape<T>;
+/**
+ * Creates a shape representing a nullable type.
+ * `Shapes.nullable(T)` corresponds to `T | null`
+ */
+export declare function nullable<T extends Shape>(shape: T): NullableShape<T>;
+export {};
+//# sourceMappingURL=shapes.d.ts.map

package/dist/shapes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shapes.d.ts","sourceRoot":"","sources":["../src/shapes/shapes.ts"],"names":[],"mappings":"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"}

package/dist/shapes.js

@@ -0,0 +1,318 @@
+"use strict";
+/// TYPE GUARDS
+// These are static functions to avoid allocating guards per Shape instance,
+// Shapes may reference these instead
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.number = number;
+exports.string = string;
+exports.boolean = boolean;
+exports.array = array;
+exports.object = object;
+exports.optional = optional;
+exports.nullable = nullable;
+function isString(input) {
+    return typeof input === "string";
+}
+function isNumber(input) {
+    return Number.isFinite(input);
+}
+function isObject(input) {
+    return input !== null && typeof input === "object" && !Array.isArray(input);
+}
+function isArray(input) {
+    return Array.isArray(input);
+}
+function isNull(input) {
+    return input === null;
+}
+function isBoolean(input) {
+    return typeof input === "boolean";
+}
+function isUndefined(input) {
+    return input === undefined;
+}
+function makeUnion(left, right) {
+    return {
+        typename: "".concat(left.typename, " | ").concat(right.typename),
+        primitive: undefined,
+        left: left,
+        right: right,
+        predicates: [],
+        where: function (p) {
+            this.predicates.push(p);
+            return this;
+        },
+        check: function (x) {
+            return (left.check(x) || right.check(x)) &&
+                this.predicates.every(function (p) { return p(x); });
+        }, // TODO: refine for objects?
+        and: function (other) {
+            return makeIntersection(this, other);
+        },
+        or: function (other) {
+            return makeUnion(this, other);
+        },
+    };
+}
+function makeIntersection(left, right) {
+    return {
+        typename: "".concat(left.typename, " | ").concat(right.typename),
+        primitive: undefined,
+        left: __assign(__assign({}, left), { 
+            // Trickery: combine permitted properties of left and right
+            properties: __assign(__assign({}, right.properties), left.properties) }),
+        right: __assign(__assign({}, right), { 
+            // Trickery: combine permitted properties of left and right
+            properties: __assign(__assign({}, left.properties), right.properties) }),
+        predicates: [],
+        where: function (p) {
+            this.predicates.push(p);
+            return this;
+        },
+        check: function (x) {
+            return this.left.check(x) && this.right.check(x) &&
+                this.predicates.every(function (p) { return p(x); });
+        },
+        and: function (other) {
+            return makeIntersection(this, other);
+        },
+        or: function (other) {
+            return makeUnion(this, other);
+        },
+    };
+}
+/// PRIMITIVE SHAPE FACTORIES
+/**
+ * Creates a shape representing a JS `number`.
+ * Does not support BigInt.
+ */
+function number() {
+    return {
+        typename: "number",
+        predicates: [],
+        primitive: undefined,
+        check: function (x) {
+            return isNumber(x) && this.predicates.every(function (p) { return p(x); });
+        },
+        where: function (p) {
+            this.predicates.push(p);
+            return this;
+        },
+        and: function (other) {
+            return makeIntersection(this, other);
+        },
+        or: function (other) {
+            return makeUnion(this, other);
+        },
+    };
+}
+/**
+ * Creates a shape representing a JS `string`.
+ */
+function string() {
+    return {
+        typename: "string",
+        primitive: undefined,
+        check: function (x) {
+            return isString(x) && this.predicates.every(function (p) { return p(x); });
+        },
+        predicates: [],
+        where: function (predicate) {
+            this.predicates.push(predicate);
+            return this;
+        },
+        and: function (other) {
+            return makeIntersection(this, other);
+        },
+        or: function (other) {
+            return makeUnion(this, other);
+        },
+    };
+}
+/**
+ * Creates a shape representing a JS `boolean`.
+ */
+function boolean() {
+    return {
+        primitive: undefined,
+        typename: "boolean",
+        check: function (x) {
+            return isBoolean(x) && this.predicates.every(function (p) { return p(x); });
+        },
+        predicates: [],
+        where: function (predicate) {
+            this.predicates.push(predicate);
+            return this;
+        },
+        and: function (other) {
+            return makeIntersection(this, other);
+        },
+        or: function (other) {
+            return makeUnion(this, other);
+        },
+    };
+}
+/// COMPLEX SHAPE FACTORIES
+/**
+ * Creates an array shape, representing `Array<T>` (aka `T[]`).
+ * Takes the shape representing `T` as a parameter.
+ */
+function array(shape) {
+    var typename = "Array<".concat(shape.typename, ">");
+    return {
+        typename: typename,
+        inner: shape,
+        primitive: undefined,
+        check: function (input) {
+            if (!isArray(input)) {
+                return false;
+            }
+            return input.every(function (entry) {
+                if (!shape.check(entry)) {
+                    return false;
+                }
+                return true;
+            }) && this.predicates.every(function (p) { return p(input); });
+        },
+        predicates: [],
+        where: function (predicate) {
+            this.predicates.push(predicate);
+            return this;
+        },
+        and: function (other) {
+            return makeIntersection(this, other);
+        },
+        or: function (other) {
+            return makeUnion(this, other);
+        },
+    };
+}
+/**
+ * Creates an object shape.
+ *
+ * @example
+ * const Group = Shapes.object({
+ *  id: Shapes.number(),
+ *  name: Shapes.string(),
+ * });
+ *
+ * const User = Shapes.object({
+ *  id: Shapes.number(),
+ *  name: Shapes.string(),
+ *  groups: Shapes.nullable(
+ *    Shapes.array(Group)
+ *   )
+ * });
+ */
+function object(properties, options) {
+    var allowUnknownProperties = options === null || options === void 0 ? void 0 : options.allowUnknownProperties;
+    return {
+        typename: "Object",
+        allowUnknownProperties: allowUnknownProperties,
+        check: function (input) {
+            // Check that input is an object
+            if (!isObject(input)) {
+                return false;
+            }
+            // Check for unknown properties
+            if (!this.allowUnknownProperties) {
+                for (var inputProperty in input) {
+                    if (!(inputProperty in this.properties)) {
+                        return false;
+                    }
+                }
+            }
+            // Check required properties and their types
+            for (var property in properties) {
+                var field = input[property];
+                var propertyShape = properties[property];
+                // Property presence check
+                if (!(property in input) && !propertyShape.optional) {
+                    return false;
+                }
+                // Property type check
+                if (!propertyShape.check(field)) {
+                    return false;
+                }
+            }
+            return this.predicates.every(function (p) { return p(input); });
+        },
+        properties: __assign(__assign({}, properties), options === null || options === void 0 ? void 0 : options.additionalPermittedProperties),
+        primitive: undefined,
+        predicates: [],
+        where: function (predicate) {
+            this.predicates.push(predicate);
+            return this;
+        },
+        and: function (other) {
+            return makeIntersection(this, other);
+        },
+        or: function (other) {
+            return makeUnion(this, other);
+        },
+    };
+}
+/// TYPE MODIFIERS
+/**
+ * Creates a shape representing an optional type.
+ * `Shapes.optional(T)` corresponds to `T | undefined`
+ */
+function optional(shape) {
+    return {
+        typename: "".concat(shape.typename, " | undefined"),
+        inner: shape,
+        optional: true,
+        primitive: undefined,
+        predicates: [],
+        check: function (input) {
+            return isUndefined(input) || shape.check(input);
+        },
+        where: function (predicate) {
+            this.inner.predicates.push(predicate);
+            return this;
+        },
+        and: function (other) {
+            return makeIntersection(this, other);
+        },
+        or: function (other) {
+            return makeUnion(this, other);
+        },
+    };
+}
+/**
+ * Creates a shape representing a nullable type.
+ * `Shapes.nullable(T)` corresponds to `T | null`
+ */
+function nullable(shape) {
+    var nullShape = {
+        typename: "".concat(shape.typename, " | null"),
+        check: function (input) {
+            return isNull(input) || shape.check(input);
+        },
+        inner: shape,
+        primitive: undefined,
+        predicates: [],
+        where: function (p) {
+            this.inner.predicates.push(p);
+            return this;
+        },
+        and: function (other) {
+            return makeIntersection(this, other);
+        },
+        or: function (other) {
+            return makeUnion(this, other);
+        },
+    };
+    return nullShape;
+}

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@jakobkg/shapes-ts",
+  "version": "0.1.0",
+  "private": false,
+  "main": "dist/index.js",
+  "scripts": {
+    "test": "deno test",
+    "test:coverage": "deno test --coverage",
+    "build": "tsc"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3"
+  }
+}