@buildinams/core 0.1.0 → 0.2.0

package/dist/navigation/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Defines the schema for parsing and stringifying states to and from hrefs.
+ *
+ * The `HrefSchema` type is a generic that takes a state shape and declares three methods:
+ *
+ * - `parse`: A function that takes an href string and returns the corresponding state object.
+ * - `stringify`: A function that takes a state object and the current href, and returns a new href string that represents the given state.
+ * - `parseStringify`: A function that takes a current href and a mutation function, and returns a new href string that represents the mutated state.
+ *
+ * This schema is used to map application state to URL hrefs and vice versa.
+ */
+type HrefSchema<State = any> = {
+    /** Parse a href string into the state shape */
+    parse: (href: string) => State & {
+        href: string;
+    };
+    /** Stringify a state shape and current href into a new href string */
+    stringify: (state: State & {
+        href: string;
+    }) => string;
+    /** Compute a new href string based on a given href and a mutation of the current state. */
+    parseStringify: (href: string, mutate: (state: State) => State) => string;
+    /**
+     * @internal
+     */
+    _template: HrefSchemaTemplate<State>;
+};
+/**
+ * A utility type to extract the state shape from a given `HrefSchema`. It infers the state type from the `HrefSchema` and adds the `href` property to it.
+ */
+type HrefSchemaState<T extends HrefSchema> = T extends HrefSchema<infer U> ? U & {
+    href: string;
+} : never;
+/**
+ * Helper function to create a `HrefSchema` from a simpler template that only requires the logic for converting between URLs and state objects. The `createSchema` function takes care of implementing the `parse`, `stringify`, and `parseStringify` methods based on the provided template functions.
+ *
+ * The template requires two functions:
+ * - `urlToState`: A function that takes a URL object and returns the corresponding state object.
+ * - `stateToUrl`: A function that takes a state object and the current URL, and returns a new URL object that represents the given state.
+ *
+ * This allows you to focus on the logic for how your application's state maps to the URL structure without having to manually handle the parsing and stringifying of hrefs.
+ */
+declare const createHrefSchema: <T>(template: HrefSchemaTemplate<T>) => HrefSchema<T>;
+type HrefSchemaTemplate<State = never> = {
+    /** Parse a href string into the state shape */
+    urlToState: (url: URL) => State;
+    /** Stringify a state shape and current href into a new href string */
+    stateToUrl: (state: State, url: URL) => URL;
+};
+
+export { type HrefSchema, type HrefSchemaState, createHrefSchema };

package/dist/navigation/index.js

@@ -0,0 +1,29 @@
+// src/navigation/href-schema.ts
+var hrefToUrl = (href) => new URL(href, "http://localhost");
+var createHrefSchema = (template) => ({
+  _template: template,
+  stringify: (state) => {
+    const current = hrefToUrl(state.href);
+    const next = template.stateToUrl(state, current);
+    return next.pathname + next.search;
+  },
+  parse: (href) => {
+    const current = hrefToUrl(href);
+    return {
+      ...template.urlToState(current),
+      href: current.pathname + current.search
+    };
+  },
+  parseStringify: (href, mutate) => {
+    const current = hrefToUrl(href);
+    const next = template.stateToUrl(
+      mutate(template.urlToState(current)),
+      current
+    );
+    return next.pathname + next.search;
+  }
+});
+
+export { createHrefSchema };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/navigation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/navigation/href-schema.ts"],"names":[],"mappings":";AAmCA,IAAM,YAAY,CAAC,IAAA,KAAiB,IAAI,GAAA,CAAI,MAAM,kBAAkB,CAAA;AAW7D,IAAM,gBAAA,GAAmB,CAC/B,QAAA,MACoB;AAAA,EACpB,SAAA,EAAW,QAAA;AAAA,EACX,SAAA,EAAW,CAAC,KAAA,KAAU;AACrB,IAAA,MAAM,OAAA,GAAU,SAAA,CAAU,KAAA,CAAM,IAAI,CAAA;AACpC,IAAA,MAAM,IAAA,GAAO,QAAA,CAAS,UAAA,CAAW,KAAA,EAAO,OAAO,CAAA;AAC/C,IAAA,OAAO,IAAA,CAAK,WAAW,IAAA,CAAK,MAAA;AAAA,EAC7B,CAAA;AAAA,EAEA,KAAA,EAAO,CAAC,IAAA,KAAS;AAChB,IAAA,MAAM,OAAA,GAAU,UAAU,IAAI,CAAA;AAC9B,IAAA,OAAO;AAAA,MACN,GAAG,QAAA,CAAS,UAAA,CAAW,OAAO,CAAA;AAAA,MAC9B,IAAA,EAAM,OAAA,CAAQ,QAAA,GAAW,OAAA,CAAQ;AAAA,KAClC;AAAA,EACD,CAAA;AAAA,EAEA,cAAA,EAAgB,CAAC,IAAA,EAAM,MAAA,KAAW;AACjC,IAAA,MAAM,OAAA,GAAU,UAAU,IAAI,CAAA;AAC9B,IAAA,MAAM,OAAO,QAAA,CAAS,UAAA;AAAA,MACrB,MAAA,CAAO,QAAA,CAAS,UAAA,CAAW,OAAO,CAAC,CAAA;AAAA,MACnC;AAAA,KACD;AACA,IAAA,OAAO,IAAA,CAAK,WAAW,IAAA,CAAK,MAAA;AAAA,EAC7B;AACD,CAAA","file":"index.js","sourcesContent":["/**\n * Defines the schema for parsing and stringifying states to and from hrefs.\n *\n * The `HrefSchema` type is a generic that takes a state shape and declares three methods:\n *\n * - `parse`: A function that takes an href string and returns the corresponding state object.\n * - `stringify`: A function that takes a state object and the current href, and returns a new href string that represents the given state.\n * - `parseStringify`: A function that takes a current href and a mutation function, and returns a new href string that represents the mutated state.\n *\n * This schema is used to map application state to URL hrefs and vice versa.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type HrefSchema<State = any> = {\n\t/** Parse a href string into the state shape */\n\tparse: (href: string) => State & { href: string };\n\t/** Stringify a state shape and current href into a new href string */\n\tstringify: (state: State & { href: string }) => string;\n\n\t/** Compute a new href string based on a given href and a mutation of the current state. */\n\tparseStringify: (href: string, mutate: (state: State) => State) => string;\n\n\t/**\n\t * @internal\n\t */\n\t_template: HrefSchemaTemplate<State>;\n};\n\n/**\n * A utility type to extract the state shape from a given `HrefSchema`. It infers the state type from the `HrefSchema` and adds the `href` property to it.\n */\nexport type HrefSchemaState<T extends HrefSchema> =\n\tT extends HrefSchema<infer U> ? U & { href: string } : never;\n\n// This is fine as we only use the `pathname` an `search` properties from the URL object,\n// which do not contain the \"https://localhost\" origin.\nconst hrefToUrl = (href: string) => new URL(href, \"http://localhost\");\n\n/**\n * Helper function to create a `HrefSchema` from a simpler template that only requires the logic for converting between URLs and state objects. The `createSchema` function takes care of implementing the `parse`, `stringify`, and `parseStringify` methods based on the provided template functions.\n *\n * The template requires two functions:\n * - `urlToState`: A function that takes a URL object and returns the corresponding state object.\n * - `stateToUrl`: A function that takes a state object and the current URL, and returns a new URL object that represents the given state.\n *\n * This allows you to focus on the logic for how your application's state maps to the URL structure without having to manually handle the parsing and stringifying of hrefs.\n */\nexport const createHrefSchema = <T>(\n\ttemplate: HrefSchemaTemplate<T>,\n): HrefSchema<T> => ({\n\t_template: template,\n\tstringify: (state) => {\n\t\tconst current = hrefToUrl(state.href);\n\t\tconst next = template.stateToUrl(state, current);\n\t\treturn next.pathname + next.search;\n\t},\n\n\tparse: (href) => {\n\t\tconst current = hrefToUrl(href);\n\t\treturn {\n\t\t\t...template.urlToState(current),\n\t\t\thref: current.pathname + current.search,\n\t\t};\n\t},\n\n\tparseStringify: (href, mutate) => {\n\t\tconst current = hrefToUrl(href);\n\t\tconst next = template.stateToUrl(\n\t\t\tmutate(template.urlToState(current)),\n\t\t\tcurrent,\n\t\t);\n\t\treturn next.pathname + next.search;\n\t},\n});\n\ntype HrefSchemaTemplate<State = never> = {\n\t/** Parse a href string into the state shape */\n\turlToState: (url: URL) => State;\n\t/** Stringify a state shape and current href into a new href string */\n\tstateToUrl: (state: State, url: URL) => URL;\n};\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@buildinams/core",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"type": "module",
 	"author": "Build in Amsterdam <development@buildinamsterdam.com> (https://www.buildinamsterdam.com/)",
 	"repository": {
@@ -25,6 +25,10 @@
 			"types": "./dist/index.d.ts",
 			"default": "./dist/index.js"
 		},
+		"./navigation": {
+			"types": "./dist/navigation/index.d.ts",
+			"default": "./dist/navigation/index.js"
+		},
 		"./store": {
 			"types": "./dist/store/index.d.ts",
 			"default": "./dist/store/index.js"
@@ -35,6 +39,9 @@
 			"*": [
 				"./dist/index.d.ts"
 			],
+			"./navigation": [
+				"./dist/navigation/index.d.ts"
+			],
 			"./store": [
 				"./dist/store/index.d.ts"
 			]