Use optional or required literal instead of optional flag

README.md

@@ -17,7 +17,7 @@ yarn add ts-routes
 
 ## Quick start
 
-```js
+```ts
 import { createRouting, number, query, segment, uuid } from 'ts-routes';
 
 const routes = createRouting({

__tests__/query.test.ts

@@ -7,7 +7,7 @@ describe("query", () => {
             product: {
                 ...segment`/product`,
                 query: {
-                    productId: query(true),
+                    productId: query("optional"),
                 },
             },
         } as const);
@@ -22,7 +22,7 @@ describe("query", () => {
             product: {
                 ...segment`/product`,
                 query: {
-                    productId: query(false),
+                    productId: query("required"),
                 },
             },
         } as const);
@@ -37,8 +37,8 @@ describe("query", () => {
             product: {
                 ...segment`/product`,
                 query: {
-                    productId: query(false),
-                    details: query(true),
+                    productId: query("required"),
+                    details: query("optional"),
                 },
             },
         } as const);
@@ -58,7 +58,7 @@ describe("query", () => {
             product: {
                 ...segment`/product`,
                 query: {
-                    filter: query(false),
+                    filter: query("required"),
                 },
                 children: {
                     details: segment`/${number("productId")}`,
@@ -76,7 +76,7 @@ describe("query", () => {
             product: {
                 ...segment`/product`,
                 query: {
-                    productId: query(true),
+                    productId: query("optional"),
                 },
             },
         } as const);

__tests__/segments/arg.test.ts

@@ -1,28 +1,6 @@
-import { string, createRouting, segment, arg } from "../../src";
+import { createRouting, segment, arg } from "../../src";
 
 describe("arg segment", () => {
-    it("creates route with an arg segment", () => {
-        const routes = createRouting({
-            product: segment`/product/${string("productId")}`,
-        } as const);
-
-        const route = routes.product({ productId: "id" });
-
-        expect(route).toEqual("/product/id");
-    });
-
-    it("creates route with an optional arg segment", () => {
-        const routes = createRouting({
-            product: segment`/product/${string("productId", {
-                optional: true,
-            })}`,
-        } as const);
-
-        const route = routes.product();
-
-        expect(route).toEqual("/product");
-    });
-
     it("creates route with a custom pattern param", () => {
         const routes = createRouting({
             product: segment`/product/${arg("productId", {
@@ -45,28 +23,6 @@ describe("arg segment", () => {
         expect(() => routes.product({ productId: "123" })).toThrow();
     });
 
-    it("returns the correct path pattern when required", () => {
-        const routes = createRouting({
-            product: segment`/product/${string("productId")}`,
-        } as const);
-
-        const pattern = routes.product.pattern;
-
-        expect(pattern).toEqual("/product/:productId");
-    });
-
-    it("returns the correct path pattern when optional", () => {
-        const routes = createRouting({
-            product: segment`/product/${string("productId", {
-                optional: true,
-            })}`,
-        } as const);
-
-        const pattern = routes.product.pattern;
-
-        expect(pattern).toEqual("/product/:productId?");
-    });
-
     it("returns the correct path pattern for custom regexes", () => {
         const routes = createRouting({
             product: segment`/product/${arg("productId", {

__tests__/segments/number.test.ts

@@ -3,7 +3,7 @@ import { createRouting, number, segment } from "../../src";
 describe("number segment", () => {
     it("creates route with an optional number param", () => {
         const routes = createRouting({
-            product: segment`/product/${number("productId", { optional: true })}`,
+            product: segment`/product/${number("productId", "optional")}`,
         } as const);
 
         const route = routes.product();
@@ -41,7 +41,7 @@ describe("number segment", () => {
 
     it("returns the correct pattern when optional", () => {
         const routes = createRouting({
-            product: segment`/product/${number("productId", { optional: true })}`,
+            product: segment`/product/${number("productId", "optional")}`,
         } as const);
 
         const pattern = routes.product.pattern;

__tests__/segments/string.test.ts

@@ -0,0 +1,43 @@
+import { string, createRouting, segment } from "../../src";
+
+describe("arg segment", () => {
+    it("creates route with an arg segment", () => {
+        const routes = createRouting({
+            product: segment`/product/${string("productId")}`,
+        } as const);
+
+        const route = routes.product({ productId: "id" });
+
+        expect(route).toEqual("/product/id");
+    });
+
+    it("creates route with an optional arg segment", () => {
+        const routes = createRouting({
+            product: segment`/product/${string("productId", "optional")}`,
+        } as const);
+
+        const route = routes.product();
+
+        expect(route).toEqual("/product");
+    });
+
+    it("returns the correct path pattern when required", () => {
+        const routes = createRouting({
+            product: segment`/product/${string("productId")}`,
+        } as const);
+
+        const pattern = routes.product.pattern;
+
+        expect(pattern).toEqual("/product/:productId");
+    });
+
+    it("returns the correct path pattern when optional", () => {
+        const routes = createRouting({
+            product: segment`/product/${string("productId", "optional")}`,
+        } as const);
+
+        const pattern = routes.product.pattern;
+
+        expect(pattern).toEqual("/product/:productId?");
+    });
+});

__tests__/segments/uuid.test.ts

@@ -5,7 +5,7 @@ describe("uuid segment", () => {
 
     it("creates route with an optional uuid param", () => {
         const routes = createRouting({
-            product: segment`/product/${uuid("productId", { optional: true })}`,
+            product: segment`/product/${uuid("productId", "optional")}`,
         } as const);
 
         const route = routes.product();

__tests__/types/index.test-d.ts

@@ -7,15 +7,15 @@ const routes = createRouting({
     products: {
         ...segment`/products`,
         query: {
-            filter: query(false),
-            optionalFilter: query(true),
-            object: query<{ test: string }, true>(true),
+            filter: query("required"),
+            optionalFilter: query("optional"),
+            object: query<{ test: string }, "optional">("optional"),
         },
         children: {
             product: segment`/${number("productId")}`,
         },
     },
-    order: segment`/orders/${number("orderId", { optional: true })}`,
+    order: segment`/orders/${number("orderId", "optional")}`,
 });
 
 // Should not allow creating routing from raw strings

package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-routes",
-  "version": "2.0.0",
+  "version": "2.0.0-alpha.0",
   "description": "Strongly typed routes management",
   "main": "lib/index.cjs.js",
   "module": "lib/index.esm.js",

src/PathParamDescription.ts

@@ -1,14 +1,19 @@
-export default class PathParamDescription<TName extends string = string, TOptional extends boolean = true> {
+import { Optionality } from "./helpers";
+
+export default class PathParamDescription<
+    TName extends string = string,
+    TOptionality extends Optionality = "optional",
+> {
     public readonly pattern: string;
     public readonly name: TName;
-    public readonly optional: TOptional;
+    public readonly optionality: TOptionality;
 
-    constructor({ name, optional, pattern }: { name: TName; optional: TOptional; pattern?: string }) {
+    constructor({ name, optionality, pattern }: { name: TName; optionality: TOptionality; pattern?: string }) {
         const patternPart = pattern ? `(${pattern})` : "";
-        const requirementPart = optional ? "?" : "";
+        const requirementPart = optionality === "optional" ? "?" : "";
 
         this.name = name;
-        this.optional = optional ?? (false as any);
+        this.optionality = optionality;
         this.pattern = `:${name}${patternPart}${requirementPart}`;
     }
 }

src/QueryParamDescription.ts

@@ -1,5 +1,7 @@
-export default class QueryParamDescription<TReturnType = string, TOptional extends boolean = false> {
+import { Optionality } from "./helpers";
+
+export default class QueryParamDescription<TReturnType = string, TOptionality extends Optionality = "required"> {
     private readonly _?: TReturnType;
 
-    constructor(public readonly optional: TOptional) {}
+    constructor(public readonly optionality: TOptionality) {}
 }

src/RouteDescription.ts

@@ -1,10 +1,11 @@
 import SegmentPattern from "./SegmentPattern";
 import QueryParamDescription from "./QueryParamDescription";
 import PathParamDescription from "./PathParamDescription";
+import { Optionality } from "./helpers";
 
 export default interface RouteDescription<
-    TPathParams extends PathParamDescription<string, boolean>[] = [],
-    TQueryParams extends Record<string, QueryParamDescription<any, boolean>> = {},
+    TPathParams extends PathParamDescription<string, Optionality>[] = [],
+    TQueryParams extends Record<string, QueryParamDescription<any, Optionality>> = {},
     TChildren extends { readonly [name: string]: RouteDescription<any, any> } = {},
 > {
     readonly pattern: SegmentPattern<TPathParams>;

src/SegmentPattern.ts

@@ -1,5 +1,6 @@
+import { Optionality } from "./helpers";
 import PathParamDescription from "./PathParamDescription";
 
-export default class SegmentPattern<TPathParamsDescription extends PathParamDescription<string, boolean>[]> {
+export default class SegmentPattern<TPathParamsDescription extends PathParamDescription<string, Optionality>[]> {
     constructor(public readonly pattern: string, public readonly params: TPathParamsDescription) {}
 }

src/createRouting.ts

@@ -1,5 +1,6 @@
 import { compile } from "path-to-regexp";
 import { IParseOptions, IStringifyOptions, parse, stringify } from "qs";
+import { Optionality } from "./helpers";
 import PathParamDescription from "./PathParamDescription";
 import QueryParamDescription from "./QueryParamDescription";
 import RouteDescription from "./RouteDescription";
@@ -53,30 +54,30 @@ type GetQueryParams<TRouteDescription extends RouteDescription<any, any, any>> =
 
 type UnionToIntersection<T> = (T extends any ? (x: T) => any : never) extends (x: infer R) => any ? R : never;
 
-type MapPathParams<TPathParams extends PathParamDescription<string, boolean>[]> = UnionToIntersection<
+type MapPathParams<TPathParams extends PathParamDescription<string, Optionality>[]> = UnionToIntersection<
     {
         [T in keyof TPathParams]: GetParam<TPathParams[T]>;
     }[number]
 >;
 
 type SingleOrArray<T> = T | T[];
 
-type MapQueryParams<TQueryParams extends Record<string, QueryParamDescription<any, boolean>>> = {
-    [TName in keyof TQueryParams as TQueryParams[TName] extends QueryParamDescription<any, true>
+type MapQueryParams<TQueryParams extends Record<string, QueryParamDescription<any, Optionality>>> = {
+    [TName in keyof TQueryParams as TQueryParams[TName] extends QueryParamDescription<any, "optional">
         ? TName
         : never]?: SingleOrArray<GetQueryResultType<TQueryParams[TName]>>;
 } &
     {
-        [TName in keyof TQueryParams as TQueryParams[TName] extends QueryParamDescription<any, false>
+        [TName in keyof TQueryParams as TQueryParams[TName] extends QueryParamDescription<any, "required">
             ? TName
             : never]: SingleOrArray<GetQueryResultType<TQueryParams[TName]>>;
     };
 
-type GetQueryResultType<TQueryParam extends QueryParamDescription<any, boolean>> =
-    TQueryParam extends QueryParamDescription<infer TReturnType, boolean> ? TReturnType : never;
+type GetQueryResultType<TQueryParam extends QueryParamDescription<any, Optionality>> =
+    TQueryParam extends QueryParamDescription<infer TReturnType, Optionality> ? TReturnType : never;
 
 type GetParam<TPathParam> = TPathParam extends PathParamDescription<infer TName, infer TOptional>
-    ? TOptional extends true
+    ? TOptional extends "optional"
         ? {
               [T in TName]?: string;
           }

src/helpers.ts

@@ -3,3 +3,5 @@ export type PathParamsFor<T extends (...args: any[]) => string> = Parameters<T>[
     : NonNullable<Parameters<T>[0]>;
 
 export type QueryParamsFor<T extends (...args: any[]) => string> = Parameters<T>[1];
+
+export type Optionality = "required" | "optional";

src/parameters/arg.ts

@@ -1,14 +1,15 @@
+import { Optionality } from "../helpers";
 import PathParamDescription from "../PathParamDescription";
 
-export default function arg<TName extends string = string, TOptional extends boolean = false>(
+export default function arg<TName extends string = string, TOptionality extends Optionality = "required">(
     name: TName,
     {
         pattern,
-        optional = false as TOptional,
+        optionality = "required" as TOptionality,
     }: {
         pattern?: string;
-        optional?: TOptional;
+        optionality?: TOptionality;
     } = {},
 ) {
-    return new PathParamDescription({ name, optional, pattern });
+    return new PathParamDescription({ name, optionality, pattern });
 }

src/parameters/number.ts

@@ -1,14 +1,22 @@
+import { Optionality } from "../helpers";
 import PathParamDescription from "../PathParamDescription";
 
-export default function uuid<TName extends string = string, TOptional extends boolean = false>(
+export default function uuid<TName extends string = string, TOptionality extends Optionality = "required">(
     name: TName,
-    {
-        optional = false as TOptional,
-    }: {
-        optional?: TOptional;
-    } = {},
+    optsOrOptionality?:
+        | {
+              optionality?: TOptionality;
+          }
+        | TOptionality,
 ) {
+    let optionality: TOptionality;
+    if (typeof optsOrOptionality === "string") {
+        optionality = optsOrOptionality;
+    } else {
+        optionality = optsOrOptionality?.optionality ?? ("required" as TOptionality);
+    }
+
     const number = "[0-9]+";
 
-    return new PathParamDescription({ name, optional, pattern: number });
+    return new PathParamDescription({ name, optionality, pattern: number });
 }

src/parameters/string.ts

@@ -1,12 +1,20 @@
+import { Optionality } from "../helpers";
 import PathParamDescription from "../PathParamDescription";
 
-export default function string<TName extends string = string, TOptional extends boolean = false>(
+export default function string<TName extends string = string, TOptionality extends Optionality = "required">(
     name: TName,
-    {
-        optional = false as TOptional,
-    }: {
-        optional?: TOptional;
-    } = {},
+    optsOrOptionality?:
+        | {
+              optionality?: TOptionality;
+          }
+        | TOptionality,
 ) {
-    return new PathParamDescription({ name, optional });
+    let optionality: TOptionality;
+    if (typeof optsOrOptionality === "string") {
+        optionality = optsOrOptionality;
+    } else {
+        optionality = optsOrOptionality?.optionality ?? ("required" as TOptionality);
+    }
+
+    return new PathParamDescription({ name, optionality });
 }