@buildinams/core 0.1.0 → 0.3.0

package/dist/chunk-IAAQVL6M.js

@@ -0,0 +1,39 @@
+// src/schema/schema.ts
+var createSchema = (template) => ({
+  ...template,
+  parserialize: (value, next) => {
+    return template.serialize(next(template.parse(value)));
+  }
+});
+
+// src/schema/string-schema.ts
+var createStringSchema = (template) => {
+  const schema = createSchema({
+    serialize: template.stringify,
+    parse: template.parse
+  });
+  return {
+    parse: schema.parse,
+    stringify: schema.serialize,
+    parseStringify: schema.parserialize
+  };
+};
+
+// src/schema/href-schema.ts
+var hrefSchema = createStringSchema({
+  parse: (href) => {
+    const [pathname = "", search = ""] = href.split("?");
+    return {
+      pathname,
+      searchParams: new URLSearchParams(search)
+    };
+  },
+  stringify: (state) => {
+    const paramsString = state.searchParams.toString();
+    return state.pathname + (paramsString ? `?${paramsString}` : "");
+  }
+});
+
+export { createSchema, createStringSchema, hrefSchema };
+//# sourceMappingURL=chunk-IAAQVL6M.js.map
+//# sourceMappingURL=chunk-IAAQVL6M.js.map

package/dist/chunk-IAAQVL6M.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema/schema.ts","../src/schema/string-schema.ts","../src/schema/href-schema.ts"],"names":[],"mappings":";AA4CO,IAAM,YAAA,GAAe,CAC3B,QAAA,MACmB;AAAA,EACnB,GAAG,QAAA;AAAA,EAEH,YAAA,EAAc,CAAC,KAAA,EAAO,IAAA,KAAS;AAC9B,IAAA,OAAO,SAAS,SAAA,CAAU,IAAA,CAAK,SAAS,KAAA,CAAM,KAAK,CAAC,CAAC,CAAA;AAAA,EACtD;AACD,CAAA;;;ACpCO,IAAM,kBAAA,GAAqB,CACjC,QAAA,KACqB;AACrB,EAAA,MAAM,SAAS,YAAA,CAAwB;AAAA,IACtC,WAAW,QAAA,CAAS,SAAA;AAAA,IACpB,OAAO,QAAA,CAAS;AAAA,GAChB,CAAA;AAED,EAAA,OAAO;AAAA,IACN,OAAO,MAAA,CAAO,KAAA;AAAA,IACd,WAAW,MAAA,CAAO,SAAA;AAAA,IAClB,gBAAgB,MAAA,CAAO;AAAA,GACxB;AACD;;;ACGO,IAAM,aAAa,kBAAA,CAGvB;AAAA,EACF,KAAA,EAAO,CAAC,IAAA,KAAS;AAChB,IAAA,MAAM,CAAC,WAAW,EAAA,EAAI,MAAA,GAAS,EAAE,CAAA,GAAI,IAAA,CAAK,MAAM,GAAG,CAAA;AACnD,IAAA,OAAO;AAAA,MACN,QAAA;AAAA,MACA,YAAA,EAAc,IAAI,eAAA,CAAgB,MAAM;AAAA,KACzC;AAAA,EACD,CAAA;AAAA,EACA,SAAA,EAAW,CAAC,KAAA,KAAU;AACrB,IAAA,MAAM,YAAA,GAAe,KAAA,CAAM,YAAA,CAAa,QAAA,EAAS;AACjD,IAAA,OAAO,KAAA,CAAM,QAAA,IAAY,YAAA,GAAe,CAAA,CAAA,EAAI,YAAY,CAAA,CAAA,GAAK,EAAA,CAAA;AAAA,EAC9D;AACD,CAAC","file":"chunk-IAAQVL6M.js","sourcesContent":["/**\n * Defines the schema for parsing and stringifying states to and from primitive values.\n *\n * The `Schema` type is a generic that takes a state shape and optional raw value type and declares three methods:\n *\n * - `parse`: A function that takes a raw value and returns the corresponding state object.\n * - `stringify`: A function that takes a state object and returns a raw value that represents the given state.\n * - `parseStringify`: A function that takes a raw value and a reducer function - it returns a new raw value that represents the reduced state.\n *\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type Schema<State = any, Serialized = any> = {\n\t/** Parse a raw value into the state shape */\n\tparse: (value: Serialized) => State;\n\t/** Serialize a state shape into a raw value */\n\tserialize: (state: State) => Serialized;\n\n\t/** Compute a new serialized value based on a given serialized value and a reducer of the current state. */\n\tparserialize: (\n\t\tvalue: Serialized,\n\t\tnext: (state: State) => State,\n\t) => Serialized;\n};\n\n/**\n * A utility type to extract the state shape from a given `Schema`.\n */\nexport type SchemaState<T extends Schema> =\n\tT extends Schema<infer U> ? U : never;\n\n/**\n * A utility type to extract the serialized value type from a given `Schema`.\n */\nexport type SchemaSerialized<T extends Schema> =\n\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\tT extends Schema<any, infer U> ? U : never;\n\n/**\n * Low-level helper function to create a basic `Schema` that receives the config for converting between serialized values and state objects.\n *\n * The template requires two functions:\n * - `parse`: A function that takes a serialized value and returns the corresponding state object.\n * - `serialize`: A function that takes a state object and returns a serialized value that represents the given state.\n */\nexport const createSchema = <S = never, R = never>(\n\ttemplate: Omit<Schema<S, R>, \"parserialize\">,\n): Schema<S, R> => ({\n\t...template,\n\n\tparserialize: (value, next) => {\n\t\treturn template.serialize(next(template.parse(value)));\n\t},\n});\n","import type { Schema } from \"./schema\";\nimport { createSchema } from \"./schema\";\n\nexport type StringSchema<State = never> = {\n\tparse: Schema<State, string>[\"parse\"];\n\tstringify: Schema<State, string>[\"serialize\"];\n\tparseStringify: Schema<State, string>[\"parserialize\"];\n};\n\n/**\n * Helper function to create a `StringSchema` which converts between strings and state objects.\n *\n * The template requires two functions:\n * - `parse`: A function that takes a string and returns the corresponding state object.\n * - `stringify`: A function that takes a state object and returns a string that represents the given state.\n */\nexport const createStringSchema = <S = never>(\n\ttemplate: Omit<StringSchema<S>, \"parseStringify\">,\n): StringSchema<S> => {\n\tconst schema = createSchema<S, string>({\n\t\tserialize: template.stringify,\n\t\tparse: template.parse,\n\t});\n\n\treturn {\n\t\tparse: schema.parse,\n\t\tstringify: schema.serialize,\n\t\tparseStringify: schema.parserialize,\n\t};\n};\n","import { createStringSchema } from \"./string-schema\";\n\n/**\n * Utility schema for parsing and stringifying href strings into structured state objects that include the pathname and URL search parameters.\n *\n *  @example\n * ```ts\n * import { createSchema, hrefSchema } from \"@buildinams/core/schema\";\n *\n * const myHrefSchema = createSchema<{\n *  page: number,\n *  // Used to compute next href - don't use directly. Use `.stringify()` instead\n *  _href: string\n * }>({\n *   parse: (href) => {\n *    const { searchParams } = hrefSchema.parse(href);\n *    return {\n *     page: parseInt(searchParams.get(\"page\"), 10) || 1,\n *     _href: href,\n *    }\n *   },\n *   serialize: (state) => {\n *    const { pathname, searchParams } = hrefSchema.parse(state._href);\n *    searchParams.delete(\"page\");\n *    if (state.page > 1) {\n *     searchParams.set(\"page\", state.page.toString());\n *    }\n *    return hrefSchema.serialize({ pathname, searchParams });\n *   }\n * });\n * ```\n */\nexport const hrefSchema = createStringSchema<{\n\tpathname: string;\n\tsearchParams: URLSearchParams;\n}>({\n\tparse: (href) => {\n\t\tconst [pathname = \"\", search = \"\"] = href.split(\"?\");\n\t\treturn {\n\t\t\tpathname,\n\t\t\tsearchParams: new URLSearchParams(search),\n\t\t};\n\t},\n\tstringify: (state) => {\n\t\tconst paramsString = state.searchParams.toString();\n\t\treturn state.pathname + (paramsString ? `?${paramsString}` : \"\");\n\t},\n});\n"]}

package/dist/navigation/index.d.ts

@@ -0,0 +1,71 @@
+import { S as Schema } from '../schema-iy92gbTC.js';
+
+/** @deprecated use `Schema` directly */
+type HrefSchema<State = never> = {
+    /** Parse a href string into the state shape */
+    parse: Schema<State & {
+        href: string;
+    }, string>["parse"];
+    /** Stringify a state shape into a href string */
+    stringify: Schema<State & {
+        href: string;
+    }, string>["serialize"];
+    /** Compute a new href string based on a given href string and a reducer of the current state. */
+    parseStringify: Schema<State & {
+        href: string;
+    }, string>["parserialize"];
+};
+/** @deprecated use `SchemaState` directly */
+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.
+ *
+ * @deprecated The `createHrefSchema` function is deprecated in favor of using the more flexible `createStringSchema` function directly with custom parsing and stringifying logic. The `createStringSchema` function can be used to achieve the same functionality without being tied specifically to hrefs, allowing for greater reuse and adaptability in different contexts.
+ *
+ * @example
+ * ```ts
+ * import { createHrefSchema } from "@buildinams/core/schema";
+ *
+ * const myHrefSchema = createHrefSchema<{
+ *  page: number,
+ * }>({
+ *   urlToState: (url) => {
+ *    return {
+ *     page: parseInt(url.searchParams.get("page") || "1", 10),
+ *    }
+ *   },
+ *   stateToUrl: (state, url) => {
+ *    url.searchParams.delete("page");
+ *    if (state.page > 1) {
+ *      url.searchParams.set("page", state.page.toString());
+ *    }
+ *    return url;
+ *   }
+ * });
+ *
+ * // Using the schema to parse a href string into state
+ * const state = myHrefSchema.parse("/products?page=2");
+ * console.log(state); // { page: 2, href: "/products?page=2" }
+ *
+ * // Using the schema to stringify a state object into a href string
+ * const href = myHrefSchema.stringify({ page: 3, href: "/products?page=2" });
+ * console.log(href); // "/products?page=3"
+ * ```
+ */
+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,22 @@
+import { createStringSchema } from '../chunk-IAAQVL6M.js';
+
+// src/navigation/href-schema.ts
+var hrefToUrl = (href) => new URL(href, "http://localhost");
+var createHrefSchema = (template) => createStringSchema({
+  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
+    };
+  }
+});
+
+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":";;;AAMA,IAAM,YAAY,CAAC,IAAA,KAAiB,IAAI,GAAA,CAAI,MAAM,kBAAkB,CAAA;AAyD7D,IAAM,gBAAA,GAAmB,CAC/B,QAAA,KAEA,kBAAA,CAAyC;AAAA,EACxC,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;AACD,CAAC","file":"index.js","sourcesContent":["// This is fine as we only use the `pathname` an `search` properties from the URL object,\n\nimport type { Schema } from \"../schema\";\nimport { createStringSchema } from \"../schema\";\n\n// which do not contain the \"https://localhost\" origin.\nconst hrefToUrl = (href: string) => new URL(href, \"http://localhost\");\n\n/** @deprecated use `Schema` directly */\nexport type HrefSchema<State = never> = {\n\t/** Parse a href string into the state shape */\n\tparse: Schema<State & { href: string }, string>[\"parse\"];\n\t/** Stringify a state shape into a href string */\n\tstringify: Schema<State & { href: string }, string>[\"serialize\"];\n\t/** Compute a new href string based on a given href string and a reducer of the current state. */\n\tparseStringify: Schema<State & { href: string }, string>[\"parserialize\"];\n};\n\n/** @deprecated use `SchemaState` directly */\nexport type HrefSchemaState<T extends HrefSchema> =\n\tT extends HrefSchema<infer U> ? U & { href: string } : never;\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 *\n * @deprecated The `createHrefSchema` function is deprecated in favor of using the more flexible `createStringSchema` function directly with custom parsing and stringifying logic. The `createStringSchema` function can be used to achieve the same functionality without being tied specifically to hrefs, allowing for greater reuse and adaptability in different contexts.\n *\n * @example\n * ```ts\n * import { createHrefSchema } from \"@buildinams/core/schema\";\n *\n * const myHrefSchema = createHrefSchema<{\n *  page: number,\n * }>({\n *   urlToState: (url) => {\n *    return {\n *     page: parseInt(url.searchParams.get(\"page\") || \"1\", 10),\n *    }\n *   },\n *   stateToUrl: (state, url) => {\n *    url.searchParams.delete(\"page\");\n *    if (state.page > 1) {\n *      url.searchParams.set(\"page\", state.page.toString());\n *    }\n *    return url;\n *   }\n * });\n *\n * // Using the schema to parse a href string into state\n * const state = myHrefSchema.parse(\"/products?page=2\");\n * console.log(state); // { page: 2, href: \"/products?page=2\" }\n *\n * // Using the schema to stringify a state object into a href string\n * const href = myHrefSchema.stringify({ page: 3, href: \"/products?page=2\" });\n * console.log(href); // \"/products?page=3\"\n * ```\n */\nexport const createHrefSchema = <T>(\n\ttemplate: HrefSchemaTemplate<T>,\n): HrefSchema<T> =>\n\tcreateStringSchema<T & { href: string }>({\n\t\tstringify: (state) => {\n\t\t\tconst current = hrefToUrl(state.href);\n\t\t\tconst next = template.stateToUrl(state, current);\n\t\t\treturn next.pathname + next.search;\n\t\t},\n\n\t\tparse: (href) => {\n\t\t\tconst current = hrefToUrl(href);\n\t\t\treturn {\n\t\t\t\t...template.urlToState(current),\n\t\t\t\thref: current.pathname + current.search,\n\t\t\t};\n\t\t},\n\t});\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/dist/schema/index.d.ts

@@ -0,0 +1,53 @@
+import { S as Schema } from '../schema-iy92gbTC.js';
+export { b as SchemaSerialized, a as SchemaState, c as createSchema } from '../schema-iy92gbTC.js';
+
+type StringSchema<State = never> = {
+    parse: Schema<State, string>["parse"];
+    stringify: Schema<State, string>["serialize"];
+    parseStringify: Schema<State, string>["parserialize"];
+};
+/**
+ * Helper function to create a `StringSchema` which converts between strings and state objects.
+ *
+ * The template requires two functions:
+ * - `parse`: A function that takes a string and returns the corresponding state object.
+ * - `stringify`: A function that takes a state object and returns a string that represents the given state.
+ */
+declare const createStringSchema: <S = never>(template: Omit<StringSchema<S>, "parseStringify">) => StringSchema<S>;
+
+/**
+ * Utility schema for parsing and stringifying href strings into structured state objects that include the pathname and URL search parameters.
+ *
+ *  @example
+ * ```ts
+ * import { createSchema, hrefSchema } from "@buildinams/core/schema";
+ *
+ * const myHrefSchema = createSchema<{
+ *  page: number,
+ *  // Used to compute next href - don't use directly. Use `.stringify()` instead
+ *  _href: string
+ * }>({
+ *   parse: (href) => {
+ *    const { searchParams } = hrefSchema.parse(href);
+ *    return {
+ *     page: parseInt(searchParams.get("page"), 10) || 1,
+ *     _href: href,
+ *    }
+ *   },
+ *   serialize: (state) => {
+ *    const { pathname, searchParams } = hrefSchema.parse(state._href);
+ *    searchParams.delete("page");
+ *    if (state.page > 1) {
+ *     searchParams.set("page", state.page.toString());
+ *    }
+ *    return hrefSchema.serialize({ pathname, searchParams });
+ *   }
+ * });
+ * ```
+ */
+declare const hrefSchema: StringSchema<{
+    pathname: string;
+    searchParams: URLSearchParams;
+}>;
+
+export { Schema, type StringSchema, createStringSchema, hrefSchema };

package/dist/schema/index.js

@@ -0,0 +1,3 @@
+export { createSchema, createStringSchema, hrefSchema } from '../chunk-IAAQVL6M.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/schema/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/schema-iy92gbTC.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Defines the schema for parsing and stringifying states to and from primitive values.
+ *
+ * The `Schema` type is a generic that takes a state shape and optional raw value type and declares three methods:
+ *
+ * - `parse`: A function that takes a raw value and returns the corresponding state object.
+ * - `stringify`: A function that takes a state object and returns a raw value that represents the given state.
+ * - `parseStringify`: A function that takes a raw value and a reducer function - it returns a new raw value that represents the reduced state.
+ *
+ */
+type Schema<State = any, Serialized = any> = {
+    /** Parse a raw value into the state shape */
+    parse: (value: Serialized) => State;
+    /** Serialize a state shape into a raw value */
+    serialize: (state: State) => Serialized;
+    /** Compute a new serialized value based on a given serialized value and a reducer of the current state. */
+    parserialize: (value: Serialized, next: (state: State) => State) => Serialized;
+};
+/**
+ * A utility type to extract the state shape from a given `Schema`.
+ */
+type SchemaState<T extends Schema> = T extends Schema<infer U> ? U : never;
+/**
+ * A utility type to extract the serialized value type from a given `Schema`.
+ */
+type SchemaSerialized<T extends Schema> = T extends Schema<any, infer U> ? U : never;
+/**
+ * Low-level helper function to create a basic `Schema` that receives the config for converting between serialized values and state objects.
+ *
+ * The template requires two functions:
+ * - `parse`: A function that takes a serialized value and returns the corresponding state object.
+ * - `serialize`: A function that takes a state object and returns a serialized value that represents the given state.
+ */
+declare const createSchema: <S = never, R = never>(template: Omit<Schema<S, R>, "parserialize">) => Schema<S, R>;
+
+export { type Schema as S, type SchemaState as a, type SchemaSerialized as b, createSchema as c };

package/package.json

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