js-routes 2.0.8 → 2.2.0

data/lib/routes.ts

@@ -3,15 +3,51 @@
  * Based on Rails RubyVariables.RAILS_VERSION routes of RubyVariables.APP_CLASS
  */
 
-type RouteParameter = unknown;
-type RouteParameters = Record<string, RouteParameter>;
-type Serializer = (value: unknown) => string;
-type RouteHelper = {
-  (...args: RouteParameter[]): string;
+type Optional<T> = { [P in keyof T]?: T[P] | null };
+type BaseRouteParameter = string | boolean | Date | number;
+type MethodRouteParameter = BaseRouteParameter | (() => BaseRouteParameter);
+type ModelRouteParameter =
+  | { id: MethodRouteParameter }
+  | { to_param: MethodRouteParameter }
+  | { toParam: MethodRouteParameter };
+type RequiredRouteParameter = BaseRouteParameter | ModelRouteParameter;
+type OptionalRouteParameter = undefined | null | RequiredRouteParameter;
+type QueryRouteParameter =
+  | OptionalRouteParameter
+  | QueryRouteParameter[]
+  | { [k: string]: QueryRouteParameter };
+type RouteParameters = Record<string, QueryRouteParameter>;
+
+type Serializable = Record<string, unknown>;
+type Serializer = (value: Serializable) => string;
+type RouteHelperExtras = {
   requiredParams(): string[];
   toString(): string;
 };
 
+type RequiredParameters<T extends number> = T extends 1
+  ? [RequiredRouteParameter]
+  : T extends 2
+  ? [RequiredRouteParameter, RequiredRouteParameter]
+  : T extends 3
+  ? [RequiredRouteParameter, RequiredRouteParameter, RequiredRouteParameter]
+  : T extends 4
+  ? [
+      RequiredRouteParameter,
+      RequiredRouteParameter,
+      RequiredRouteParameter,
+      RequiredRouteParameter
+    ]
+  : RequiredRouteParameter[];
+
+type RouteHelperOptions<T extends string> = RouteOptions &
+  Optional<Record<T, OptionalRouteParameter>>;
+
+type RouteHelper<T extends number = number, U extends string = string> = ((
+  ...args: [...RequiredParameters<T>, RouteHelperOptions<U>]
+) => string) &
+  RouteHelperExtras;
+
 type RouteHelpers = Record<string, RouteHelper>;
 
 type Configuration = {
@@ -21,7 +57,6 @@ type Configuration = {
   serializer: Serializer;
 };
 
-type Optional<T> = { [P in keyof T]?: T[P] | null };
 interface RouterExposedMethods {
   config(): Configuration;
   configure(arg: Partial<Configuration>): Configuration;
@@ -32,14 +67,16 @@ type KeywordUrlOptions = Optional<{
   host: string;
   protocol: string;
   subdomain: string;
-  port: string;
+  port: string | number;
   anchor: string;
   trailing_slash: boolean;
 }>;
 
-type PartsTable = Record<string, { r?: boolean; d?: unknown }>;
+type RouteOptions = KeywordUrlOptions & RouteParameters;
+
+type PartsTable = Record<string, { r?: boolean; d?: OptionalRouteParameter }>;
 
-type ModuleType = "CJS" | "AMD" | "UMD" | "ESM" | "NIL";
+type ModuleType = "CJS" | "AMD" | "UMD" | "ESM" | "DTS" | "NIL";
 
 declare const RubyVariables: {
   PREFIX: string;
@@ -92,8 +129,9 @@ RubyVariables.WRAPPER(
     }[keyof RouteNodes];
 
     const Root = that;
+    const isBroswer = typeof window !== "undefined";
     type ModuleDefinition = {
-      define: (routes: unknown) => void;
+      define: (routes: RouterExposedMethods) => void;
       isSupported: () => boolean;
     };
     const ModuleReferences: Record<ModuleType, ModuleDefinition> = {
@@ -152,7 +190,16 @@ RubyVariables.WRAPPER(
           Utils.namespace(Root, RubyVariables.NAMESPACE, routes);
         },
         isSupported() {
-          return !!Root;
+          return !RubyVariables.NAMESPACE || !!Root;
+        },
+      },
+      DTS: {
+        // Acts the same as ESM
+        define(routes) {
+          ModuleReferences.ESM.define(routes);
+        },
+        isSupported() {
+          return ModuleReferences.ESM.isSupported();
         },
       },
     };
@@ -225,16 +272,16 @@ RubyVariables.WRAPPER(
         return result.join("&");
       }
 
-      serialize(object: unknown): string {
+      serialize(object: Serializable): string {
         return this.configuration.serializer(object);
       }
 
       extract_options(
         number_of_params: number,
-        args: RouteParameter[]
+        args: OptionalRouteParameter[]
       ): {
-        args: RouteParameter[];
-        options: KeywordUrlOptions & RouteParameters;
+        args: OptionalRouteParameter[];
+        options: RouteOptions;
       } {
         const last_el = args[args.length - 1];
         if (
@@ -247,32 +294,27 @@ RubyVariables.WRAPPER(
           }
           return {
             args: args.slice(0, args.length - 1),
-            options: last_el as KeywordUrlOptions & RouteParameters,
+            options: (last_el as any) as RouteOptions,
           };
         } else {
           return { args, options: {} };
         }
       }
 
-      looks_like_serialized_model(
-        object: any
-      ): object is
-        | { id: unknown }
-        | { to_param: unknown }
-        | { toParam: unknown } {
+      looks_like_serialized_model(object: any): object is ModelRouteParameter {
         return (
           this.is_object(object) &&
-          !object[this.configuration.special_options_key] &&
+          !(this.configuration.special_options_key in object) &&
           ("id" in object || "to_param" in object || "toParam" in object)
         );
       }
 
-      path_identifier(object: unknown): string {
+      path_identifier(object: QueryRouteParameter): string {
         const result = this.unwrap_path_identifier(object);
         return this.is_nullable(result) || result === false ? "" : "" + result;
       }
 
-      unwrap_path_identifier(object: any): unknown {
+      unwrap_path_identifier(object: QueryRouteParameter): unknown {
         let result: any = object;
         if (!this.is_object(object)) {
           return object;
@@ -293,7 +335,7 @@ RubyVariables.WRAPPER(
         parts: string[],
         required_params: string[],
         default_options: RouteParameters,
-        call_arguments: RouteParameter[]
+        call_arguments: OptionalRouteParameter[]
       ): {
         keyword_parameters: KeywordUrlOptions;
         query_parameters: RouteParameters;
@@ -307,7 +349,9 @@ RubyVariables.WRAPPER(
           throw new Error("Too many parameters provided for path");
         }
         let use_all_parts = args.length > required_params.length;
-        const parts_options: RouteParameters = {};
+        const parts_options: RouteParameters = {
+          ...this.configuration.default_url_options,
+        };
         for (const key in options) {
           const value = options[key];
           if (!hasProp(options, key)) continue;
@@ -357,7 +401,7 @@ RubyVariables.WRAPPER(
         default_options: RouteParameters,
         route: RouteTree,
         absolute: boolean,
-        args: RouteParameter[]
+        args: OptionalRouteParameter[]
       ): string {
         const {
           keyword_parameters,
@@ -467,9 +511,9 @@ RubyVariables.WRAPPER(
       }
 
       encode_segment(segment: string): string {
-        return segment.replace(UriEncoderSegmentRegex, function (str) {
-          return encodeURIComponent(str);
-        });
+        return segment.replace(UriEncoderSegmentRegex, (str) =>
+          encodeURIComponent(str)
+        );
       }
 
       is_optional_node(node: NodeTypes): boolean {
@@ -550,7 +594,7 @@ RubyVariables.WRAPPER(
             default_options[part] = value;
           }
         }
-        const result = (...args: RouteParameter[]): string => {
+        const result = (...args: OptionalRouteParameter[]): string => {
           return this.build_route(
             parts,
             required_params,
@@ -564,7 +608,7 @@ RubyVariables.WRAPPER(
         result.toString = () => {
           return this.build_path_spec(route_spec);
         };
-        return result;
+        return result as any;
       }
 
       route_url(route_defaults: KeywordUrlOptions): string {
@@ -583,31 +627,18 @@ RubyVariables.WRAPPER(
         return protocol + "://" + subdomain + hostname + port;
       }
 
-      has_location(): boolean {
-        return this.is_not_nullable(window) && !!window.location;
-      }
-
-      current_host(): string | null {
-        if (this.has_location()) {
-          return window.location.hostname;
-        } else {
-          return null;
-        }
+      current_host(): string {
+        return (isBroswer && window?.location?.hostname) || "";
       }
 
       current_protocol(): string {
-        if (this.has_location() && window.location.protocol !== "") {
-          return window.location.protocol.replace(/:$/, "");
-        } else {
-          return "http";
-        }
+        return (
+          (isBroswer && window?.location?.protocol?.replace(/:$/, "")) || "http"
+        );
       }
+
       current_port(): string {
-        if (this.has_location() && window.location.port !== "") {
-          return window.location.port;
-        } else {
-          return "";
-        }
+        return (isBroswer && window?.location?.port) || "";
       }
 
       is_object(value: unknown): value is Record<string, unknown> {
@@ -633,17 +664,17 @@ RubyVariables.WRAPPER(
         object: any,
         namespace: string | null | undefined,
         routes: unknown
-      ): unknown {
+      ): void {
         const parts = namespace?.split(".") || [];
         if (parts.length === 0) {
-          return routes;
+          return;
         }
         for (let index = 0; index < parts.length; index++) {
           const part = parts[index];
           if (index < parts.length - 1) {
             object = object[part] || (object[part] = {});
           } else {
-            return (object[part] = routes);
+            object[part] = routes;
           }
         }
       }
@@ -694,7 +725,7 @@ RubyVariables.WRAPPER(
       config: (): Configuration => {
         return Utils.config();
       },
-      serialize: (object: unknown): string => {
+      serialize: (object: Serializable): string => {
         return Utils.serialize(object);
       },
       ...RubyVariables.ROUTES_OBJECT,

data/lib/tasks/js_routes.rake

@@ -1,8 +1,14 @@
 namespace :js do
-  desc "Make a js file that will have functions that will return restful routes/urls."
+  desc "Make a js file with all rails route URL helpers"
   task routes: :environment do
     require "js-routes"
-
     JsRoutes.generate!
   end
+
+  namespace :routes do
+    desc "Make a js file with all rails route URL helpers and typescript definitions for them"
+    task typescript: "js:routes" do
+      JsRoutes.definitions!
+    end
+  end
 end

data/lib/templates/erb.js

@@ -0,0 +1,11 @@
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.erb$/,
+        enforce: 'pre',
+        loader: 'rails-erb-loader'
+      },
+    ]
+  }
+};

data/lib/templates/initializer.rb

@@ -0,0 +1,5 @@
+JsRoutes.setup do |c|
+  # Setup your JS module system:
+  # ESM, CJS, AMD, UMD or nil
+  # c.module_type = "ESM"
+end

data/lib/templates/routes.js.erb

@@ -0,0 +1 @@
+<%= JsRoutes.generate %>

data/spec/js_routes/module_types/amd_spec.rb

@@ -3,11 +3,12 @@ require "spec_helper"
 describe JsRoutes, "compatibility with AMD/require.js"  do
 
   before(:each) do
-    evaljs("window.GlobalCheck = {};")
-    evaljs("window.define = function (requirs, callback) { window.GlobalCheck['js-routes'] = callback.call(this); return window.GlobalCheck['js-routes']; };")
-    evaljs("window.define.amd = { jQuery: true };")
+    evaljs("var global = this;", {force: true})
+    evaljs("global.GlobalCheck = {};")
+    evaljs("global.define = function (requirs, callback) { global.GlobalCheck['js-routes'] = callback.call(this); return global.GlobalCheck['js-routes']; };")
+    evaljs("global.define.amd = { jQuery: true };")
     strRequire =<<EOF
-    window.require = function (r, callback) {
+    global.require = function (r, callback) {
       var allArgs, i;
 
       allArgs = (function() {
@@ -15,7 +16,7 @@ describe JsRoutes, "compatibility with AMD/require.js"  do
         _results = [];
         for (_i = 0, _len = r.length; _i < _len; _i++) {
           i = r[_i];
-          _results.push(window.GlobalCheck[i]);
+          _results.push(global.GlobalCheck[i]);
         }
         return _results;
       })();

data/spec/js_routes/module_types/dts/routes.spec.d.ts

@@ -0,0 +1,114 @@
+/**
+ * File generated by js-routes RubyVariables.GEM_VERSION
+ * Based on Rails RubyVariables.RAILS_VERSION routes of RubyVariables.APP_CLASS
+ */
+declare type Optional<T> = {
+    [P in keyof T]?: T[P] | null;
+};
+declare type BaseRouteParameter = string | boolean | Date | number;
+declare type MethodRouteParameter = BaseRouteParameter | (() => BaseRouteParameter);
+declare type ModelRouteParameter = {
+    id: MethodRouteParameter;
+} | {
+    to_param: MethodRouteParameter;
+} | {
+    toParam: MethodRouteParameter;
+};
+declare type RequiredRouteParameter = BaseRouteParameter | ModelRouteParameter;
+declare type OptionalRouteParameter = undefined | null | RequiredRouteParameter;
+declare type QueryRouteParameter = OptionalRouteParameter | QueryRouteParameter[] | {
+    [k: string]: QueryRouteParameter;
+};
+declare type RouteParameters = Record<string, QueryRouteParameter>;
+declare type Serializable = Record<string, unknown>;
+declare type Serializer = (value: Serializable) => string;
+declare type RouteHelperExtras = {
+    requiredParams(): string[];
+    toString(): string;
+};
+declare type RequiredParameters<T extends number> = T extends 1 ? [RequiredRouteParameter] : T extends 2 ? [RequiredRouteParameter, RequiredRouteParameter] : T extends 3 ? [RequiredRouteParameter, RequiredRouteParameter, RequiredRouteParameter] : T extends 4 ? [
+    RequiredRouteParameter,
+    RequiredRouteParameter,
+    RequiredRouteParameter,
+    RequiredRouteParameter
+] : RequiredRouteParameter[];
+declare type RouteHelperOptions<T extends string> = RouteOptions & Optional<Record<T, OptionalRouteParameter>>;
+declare type RouteHelper<T extends number = number, U extends string = string> = ((...args: [...RequiredParameters<T>, RouteHelperOptions<U>]) => string) & RouteHelperExtras;
+declare type RouteHelpers = Record<string, RouteHelper>;
+declare type Configuration = {
+    prefix: string;
+    default_url_options: RouteParameters;
+    special_options_key: string;
+    serializer: Serializer;
+};
+interface RouterExposedMethods {
+    config(): Configuration;
+    configure(arg: Partial<Configuration>): Configuration;
+    serialize: Serializer;
+}
+declare type KeywordUrlOptions = Optional<{
+    host: string;
+    protocol: string;
+    subdomain: string;
+    port: string | number;
+    anchor: string;
+    trailing_slash: boolean;
+}>;
+declare type RouteOptions = KeywordUrlOptions & RouteParameters;
+declare type PartsTable = Record<string, {
+    r?: boolean;
+    d?: OptionalRouteParameter;
+}>;
+declare type ModuleType = "CJS" | "AMD" | "UMD" | "ESM" | "DTS" | "NIL";
+declare const RubyVariables: {
+    PREFIX: string;
+    DEPRECATED_GLOBBING_BEHAVIOR: boolean;
+    SPECIAL_OPTIONS_KEY: string;
+    DEFAULT_URL_OPTIONS: RouteParameters;
+    SERIALIZER: Serializer;
+    NAMESPACE: string;
+    ROUTES_OBJECT: RouteHelpers;
+    MODULE_TYPE: ModuleType;
+    WRAPPER: <T>(callback: T) => T;
+};
+declare const define: undefined | (((arg: unknown[], callback: () => unknown) => void) & {
+    amd?: unknown;
+});
+declare const module: {
+    exports: any;
+} | undefined;
+export const configure: RouterExposedMethods['configure'];
+
+export const config: RouterExposedMethods['config'];
+
+export const serialize: RouterExposedMethods['serialize'];
+
+/**
+ * Generates rails route to
+ * /inboxes/:inbox_id/messages/:message_id/attachments/:id(.:format)
+ * @param {any} inbox_id
+ * @param {any} message_id
+ * @param {any} id
+ * @param {object | undefined} options
+ * @returns {string} route path
+ */
+export const inbox_message_attachment_path: ((
+  inbox_id: RequiredRouteParameter,
+  message_id: RequiredRouteParameter,
+  id: RequiredRouteParameter,
+  options?: {format?: OptionalRouteParameter} & RouteOptions
+) => string) & RouteHelperExtras;
+
+/**
+ * Generates rails route to
+ * /inboxes(.:format)
+ * @param {object | undefined} options
+ * @returns {string} route path
+ */
+export const inboxes_path: ((
+  options?: {format?: OptionalRouteParameter} & RouteOptions
+) => string) & RouteHelperExtras;
+
+// By some reason this line prevents all types in a file
+// from being automatically exported
+export {};

data/spec/js_routes/module_types/dts/test.spec.ts

@@ -0,0 +1,56 @@
+import {
+  inbox_message_attachment_path,
+  inboxes_path,
+  serialize,
+  configure,
+  config,
+} from "./routes.spec";
+
+// Route Helpers
+inboxes_path();
+inboxes_path({
+  locale: "en",
+  search: {
+    q: "ukraine",
+    page: 3,
+    keywords: ["large", "small", { advanced: true }],
+  },
+});
+
+inbox_message_attachment_path(1, "2", true);
+inbox_message_attachment_path(
+  { id: 1 },
+  { to_param: () => "2" },
+  { toParam: () => true }
+);
+inbox_message_attachment_path(1, "2", true, { format: "json" });
+inboxes_path.toString();
+inboxes_path.requiredParams();
+
+// serialize test
+const SerializerArgument = {
+  locale: "en",
+  search: {
+    q: "ukraine",
+    page: 3,
+    keywords: ["large", "small", { advanced: true }],
+  },
+};
+serialize(SerializerArgument);
+config().serializer(SerializerArgument);
+
+// configure test
+configure({
+  default_url_options: { port: 1, host: null },
+  prefix: "",
+  special_options_key: "_options",
+  serializer: (value) => JSON.stringify(value),
+});
+
+// config tests
+const Config = config();
+console.log(
+  Config.prefix,
+  Config.default_url_options,
+  Config.special_options_key
+);

data/spec/js_routes/module_types/dts_spec.rb

@@ -0,0 +1,111 @@
+
+require "active_support/core_ext/string/strip"
+require "fileutils"
+require "open3"
+require "spec_helper"
+
+describe JsRoutes, "compatibility with DTS"  do
+
+  OPTIONS = {module_type: 'DTS', include: [/^inboxes$/, /^inbox_message_attachment$/]}
+  let(:extra_options) do
+    {}
+  end
+
+  let(:generated_js) do
+    JsRoutes.generate({**OPTIONS, **extra_options})
+  end
+
+  context "when file is generated" do
+    let(:dir_name) do
+       File.expand_path(__dir__ + "/dts")
+    end
+
+    let(:file_name) do
+      dir_name + "/routes.spec.d.ts"
+    end
+
+    before do
+      FileUtils.mkdir_p(dir_name)
+      File.write(file_name, generated_js)
+    end
+
+    it "has no compile errors", :slow do
+      command = "yarn tsc --strict --noEmit -p spec/tsconfig.json"
+      stdout, stderr, status = Open3.capture3(command)
+      expect(stderr).to eq("")
+      expect(stdout).to include("Done in ")
+      expect(status).to eq(0)
+    end
+  end
+
+  context "when camel case is enabled" do
+    let(:extra_options) { {camel_case: true} }
+
+    it "camelizes route name and arguments" do
+
+      expect(generated_js).to include(<<-DOC.rstrip)
+/**
+ * Generates rails route to
+ * /inboxes/:inbox_id/messages/:message_id/attachments/:id(.:format)
+ * @param {any} inboxId
+ * @param {any} messageId
+ * @param {any} id
+ * @param {object | undefined} options
+ * @returns {string} route path
+ */
+export const inboxMessageAttachmentPath: ((
+  inboxId: RequiredRouteParameter,
+  messageId: RequiredRouteParameter,
+  id: RequiredRouteParameter,
+  options?: {format?: OptionalRouteParameter} & RouteOptions
+) => string) & RouteHelperExtras;
+DOC
+    end
+  end
+
+  it "exports route helpers" do
+    expect(generated_js).to include(<<-DOC.rstrip)
+/**
+ * Generates rails route to
+ * /inboxes(.:format)
+ * @param {object | undefined} options
+ * @returns {string} route path
+ */
+export const inboxes_path: ((
+  options?: {format?: OptionalRouteParameter} & RouteOptions
+) => string) & RouteHelperExtras;
+DOC
+    expect(generated_js).to include(<<-DOC.rstrip)
+/**
+ * Generates rails route to
+ * /inboxes/:inbox_id/messages/:message_id/attachments/:id(.:format)
+ * @param {any} inbox_id
+ * @param {any} message_id
+ * @param {any} id
+ * @param {object | undefined} options
+ * @returns {string} route path
+ */
+export const inbox_message_attachment_path: ((
+  inbox_id: RequiredRouteParameter,
+  message_id: RequiredRouteParameter,
+  id: RequiredRouteParameter,
+  options?: {format?: OptionalRouteParameter} & RouteOptions
+) => string) & RouteHelperExtras
+DOC
+  end
+
+  it "exports utility methods" do
+    expect(generated_js).to include("export const serialize: RouterExposedMethods['serialize'];")
+  end
+
+  it "prevents all types from automatic export" do
+    expect(generated_js).to include("export {};")
+  end
+
+  describe "compiled javascript asset" do
+    subject { ERB.new(File.read("app/assets/javascripts/js-routes.js.erb")).result(binding) }
+    it "should have js routes code" do
+      is_expected.to include("export const inbox_message_path = __jsr.r(")
+    end
+  end
+end