@buildinams/core 0.3.1 → 0.4.0

package/docs/decisions/011-tracking-decoupled.md

@@ -0,0 +1,30 @@
+# Tracking reports to listeners; analytics takes trackers as sources
+
+Date: 2026-11-11
+
+Status: accepted
+
+## Context
+
+The markup and cart trackers took the analytics instance, and per-event handlers typed by it. That tied them to analytics for tracking, for ordering (`ecommerce()` subscribed to the instance to flush batched views), and for types (plugins created outside the call needed annotations).
+
+Decoupled, every project wrote the same glue, `domWatcher.subscribe(({ name, payload }) => analytics.track(name, payload))`. A module re-run by HMR subscribed again and tracked everything twice unless it unsubscribed first.
+
+Options considered: keep the instance and return typed helpers, depend on a structural `{ track, subscribe }`, or report to a callback; and for the glue, a `connect(analytics, tracker)` helper or `sources` on `createAnalytics()`.
+
+## Decision
+
+- **Trackers report occurrences to listeners.** `createDomWatcher(plugins)` and `createCartChanges<Item>()` have no side effects; `subscribe(listener)` hands what they report (`clicked`, `itemsViewed`, `addedToCart`, …) to whoever listens, and the first subscription starts them.
+- **`createAnalytics({ sources })`** tracks what trackers report under the same name. Every event a source reports must be in the catalog with a compatible payload. A source feeds one instance: a later `createAnalytics()` with it takes it over.
+- **Plugins carry their types.** `track()` comes from the watcher and only takes its plugins' types; plugins take the project's own fields, e.g. `clicks<{ cta: string }>()`.
+- **Ordering lives in the watcher:** `ecommerce()` flushes its batch before anything else the watcher reports. `domWatcher.flush()` and `domWatcher.newPage()` cover events tracked outside it.
+- **Its own exports:** `@buildinams/core/tracking/dom` and `/tracking/cart` import nothing from analytics but the catalog types and `shape()`.
+
+## Consequences
+
+- Trackers work with any sink: analytics, `dataLayer`, a test spy.
+- HMR re-running the analytics module doesn't double-track, and `createAnalytics()` is what visibly starts the trackers.
+- Renaming an occurrence means subscribing yourself instead of using `sources`, and handling HMR yourself; `track()` checks the result against the catalog.
+- `track()` comes from the project's tracking module, which server components can import.
+- A cart change can reach destinations before views `ecommerce()` still batches; GA4 doesn't need that order.
+- A tracker nobody subscribes to tracks nothing, silently. `createCartChanges()` holds the last cart passed before its first `subscribe()`.

package/docs/tracking.md

@@ -0,0 +1,221 @@
+# Tracking
+
+Two trackers report what happens, so call sites don't have to:
+
+- **`createDomWatcher(plugins)`** from `@buildinams/core/tracking/dom`: page views, product and promotion views and selections, clicks, videos, forms and scroll depth, from marked elements.
+- **`createCartChanges<CartItem>()`** from `@buildinams/core/tracking/cart`: adds and removes, from the confirmed carts you pass it.
+
+They track nothing themselves: they report an _occurrence_ to their `subscribe()` listeners, and do nothing until the first one. Usually that's [`createAnalytics({ sources })`](analytics.md#sources), which tracks each under the same name; their `events` are the catalog entries for it. Create them in a module without side effects, so server components can import `track()`.
+
+## What they report
+
+| Reported by                                                  | Occurrences                                                                                             |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
+| `pageViews()`, `clicks()`, `videos()`, `forms()`, `scroll()` | `pageViewed`, `clicked`, `videoStarted`/`Progressed`/`Completed`, `formStarted`/`Submitted`, `scrolled` |
+| `ecommerce()`                                                | `itemViewed`, `itemSelected`, `itemsViewed`, `promotionViewed`, `promotionSelected`                     |
+| `createCartChanges()`                                        | `addedToCart`, `removedFromCart`                                                                        |
+
+Markup fields are the library's, in camelCase (`elementId`, `videoPercent`, …), plus the plugin's own; ecommerce and cart occurrences have a fixed structure with your data in it:
+
+| Occurrence          | Payload                                                   | Placement                                                                      |
+| ------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `itemViewed`        | `{ item, list?, index?, promotion? }`                     | Where the product was last selected, e.g. the list whose card opened its page. |
+| `itemSelected`      | `{ item, list?, index?, promotion? }`                     | The list the item is in, its position from 0, and the promotion around it.     |
+| `itemsViewed`       | `{ list?, items: { item, index?, promotion? }[] }`        | One per list and batch; without a list for items outside any.                  |
+| `promotionViewed`   | `{ promotion, items }`                                    | `items` are the products featured in it outside a list; `[]` when none.        |
+| `promotionSelected` | `{ promotion, item? }`                                    | `item` when the click was on a featured product.                               |
+| `addedToCart`, …    | `{ currency, value, items: { item, quantity, price }[] }` | See [Tracking the cart](#cart).                                                |
+
+## Subscribing
+
+To track an occurrence under another name, or not at all, subscribe yourself instead of passing the tracker to `sources`. `event` is a union of what the tracker reports, so `switch (event.name)` narrows it:
+
+```ts
+domWatcher.subscribe((event) => {
+	switch (event.name) {
+		case "itemsViewed":
+			return analytics.track("productListViewed", {
+				list: event.payload.list,
+				products: event.payload.items.map(({ item }) => item),
+			});
+		case "promotionViewed":
+		case "promotionSelected":
+			return;
+	}
+	analytics.track(event.name, event.payload);
+});
+```
+
+- **Only some events:** `subscribe("clicked", listener)` or `subscribe(["itemsViewed", "itemSelected"], listener)`, narrowed by name.
+- **The element:** markup occurrences, except `ecommerce()`'s, have `element`: the page root, link, `<video>`, `<form>` or scrolled element.
+- **Errors are isolated:** a listener that throws is logged as `[analytics] <occurrence>`, and the others still receive it.
+- **Subscribe once:** a module that subscribes and re-runs, e.g. on HMR, unsubscribes first, or events are tracked twice. `sources` handles this for you.
+- **Map them yourself:** mapping builders like `ga4Mapping()` only cover the occurrences' names.
+
+## Markup
+
+`createDomWatcher(plugins)` reports what happens on marked elements, with one listener per event type on the root. Elements say what they are with space-separated types in `data-track`, written by the watcher's `track(spec)`: one object with a key per type, whose props you spread on the element.
+
+- **Attribute types**, for page views, clicks, locations, auto tracking, videos, forms and scroll, take a few strings, written as plain attributes, e.g. `track({ form: { id: "newsletter" } })` is `data-track="form" data-track-id="newsletter"`. Types whose fields are all optional take `true`: `track({ form: true })`. Server components and CMS templates can write them.
+- **Data types**, for products, lists and promotions (`viewItem`, `quickView`, `list`, `item`, `promotion`), take your data and add a `ref`, which sets it on the element from a client component, so it stays out of the HTML ([Element data](#element-data), [ADR 003](decisions/003-tracking-element-data.md)).
+
+Nothing is tracked without its type ([ADR 002](decisions/002-tracking-dom-opt-in.md)). The first `subscribe()` starts the plugins on `root` (`createDomWatcher(plugins, { root })`, `document` by default), and the last unsubscribe stops them. The watcher also has `events` for the catalog, `newPage()` ([Page views without `pageViews()`](#page-views-without-pageviews)) and `flush()`.
+
+```ts
+export const domWatcher = createDomWatcher([
+	pageViews(),
+	ecommerce<{ item: Item; list: List; promotion: Promotion }>({
+		id: ({ product }) => product.id,
+	}),
+	clicks(),
+	videos(),
+	forms(),
+	scroll(),
+]);
+
+export const { track } = domWatcher;
+```
+
+| Markup                                                        | Plugin                | Reports                                                                                                 |
+| ------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------- |
+| `track({ pageView: { pageType } })` on each page's root       | `pageViews()`         | `pageViewed` when it appears or is shown again, once per URL                                            |
+| `track({ viewItem: { product, variant } })` on a product page | `ecommerce()`         | `itemViewed` when visible, once per URL for each product (by `id`)                                      |
+| `track({ quickView: item })`                                  | `ecommerce()`         | `itemViewed` each time it opens                                                                         |
+| `track({ promotion })`                                        | `ecommerce()`         | `promotionViewed` once per page, `promotionSelected` for clicks inside                                  |
+| `track({ list })`                                             | `ecommerce()`         | Places the items inside it in the list, with their `index`                                              |
+| `track({ item: { product } })` on each product                | `ecommerce()`         | `itemsViewed` once per page, batched per list; `itemSelected` for clicks inside                         |
+| `track({ auto: ["links", "forms"] })` on an area              | `clicks()`, `forms()` | `clicked` for each `<a href>` and form events for each form inside. `false` turns it off for a subtree. |
+| `track({ location: { name: "header" } })` on an area          | `clicks()`            | `location` on every `clicked` inside it                                                                 |
+| `track({ click: { id: "size-guide" } })` on a button or link  | `clicks()`            | `clicked` with `elementId`, `url`, `text` and `outbound`. Unmarked buttons aren't tracked.              |
+| `track({ video: { title } })` on a `<video>` or an ancestor   | `videos()`            | `videoStarted`, `videoProgressed` at 10, 25, 50 and 75%, `videoCompleted`                               |
+| `track({ form: { id: "newsletter" } })` on a form             | `forms()`             | `formStarted` on the first input, once per page; `formSubmitted`. Never field values.                   |
+| `track({ scroll: { id } })` on a page's root or an article    | `scroll()`            | `scrolled` with `percentScrolled` at 25, 50, 75 and 90% (`scroll({ thresholds })`), once per URL        |
+
+- **Only what's installed:** `track()` only takes the types of the watcher's plugins, e.g. `track({ form: true })` is a compile error without `forms()`, and `auto` without `clicks()` or `forms()`.
+- **Your own fields:** `clicks<{ cta: string }>()` makes `track({ click: { cta } })` require `cta`, written as `data-track-click-cta`, and adds it to `clicked`. The other plugins take fields the same way.
+- **By hand**, e.g. in a CMS: `data-track="auto-links"`, `data-track="click" data-track-id="size-guide"`, `data-track="location" data-track-name="footer"`. Types are kebab-case in HTML: `page-view`, `auto-none`. Without an id, `click`, `form` and `scroll` fall back to the element's `id`. A comma between types makes a different type, which nothing tracks.
+- **Combining:** several types on one element are one `track()` call with a key for each, as spreading two keeps only the last `data-track`. React passes a spread `ref` through:
+
+  ```tsx
+  <section {...track({ promotion, location: { name: "hero" } })}>
+  ```
+
+- **One of each plugin per root:** watchers with different plugins work side by side; a watcher started later with the same kind replaces the earlier one's, e.g. after HMR. Plugins handle an event in the table's order, so `itemSelected` comes before `clicked`. Custom plugins aren't supported yet.
+
+### Behaviour
+
+- **Page views** are reported when the element is added or shown again, so put it on each page's root. Hidden elements wait until shown: Next.js with Cache Components keeps visited pages mounted but hidden in `<Activity>`. A query string change doesn't remount the page: key the element on the search params to count those.
+- **Product views** count when half visible, or filling half the viewport (`ecommerce({ threshold })`), so a closed `<dialog>` or hidden overlay doesn't count. Use an element with a box, not `display: contents`. A variant counts again only when it changes the URL (with the Navigation API, also when the URL changes after the data); a quick view once per opening. A page opened in a background tab counts once shown.
+- **Placement:** a product selected from a list gets its `list`, `index` and `promotion` on its next `itemViewed`, also in a quick view outside the list or on its product page, matched by `ecommerce()`'s `id`. The tab keeps the placements of the last 50 products selected in `sessionStorage` (`ecommerce({ storageKey })`, default `"analytics-placements"`), so a page loaded in full gets them too; change the key when your list's or promotion's shape changes. Without `id`, the item's JSON is its id, so a card's `{ product }` won't match a page's `{ product, variant }`.
+- **Views are batched** for 500 ms (`ecommerce({ batchDelay })`) or 30 per list, and reported before anything else the watcher reports, and when the visitor leaves. Events tracked elsewhere don't wait; call `domWatcher.flush()` first when the order matters.
+- **After a client-side navigation**, products and promotions still in view are viewed again: after `pageViewed`, `domWatcher.newPage()`, or else the first event after the path changes.
+- **Auto tracking:** put `track({ auto: ["links", "forms"] })` on the header, navigation and footer, with a `location`, so reports can group clicks. A rich-text renderer wraps its output in `track({ auto: "links" })`. The nearest `auto` decides; `click` and `form` on an element still track it.
+- **Stable ids:** link text changes with the locale and generated ids (`useId()`) between builds, so give what reports use a fixed `id`.
+- **Videos** are opt-in, so decorative loops aren't tracked; looping videos never complete. YouTube and Vimeo embeds aren't covered.
+- **Scroll depth** is how much of the element has passed the bottom of the viewport, checked per frame while scrolling, also for a restored scroll position. Hidden elements aren't tracked.
+- **Forms:** `formSubmitted` fires when the browser submits, after built-in validation, even if a handler then cancels it.
+
+### Element data
+
+A data type's `ref` sets the data after mount, so only client components can set it.
+
+```tsx
+"use client";
+
+const ProductGridItem = ({ product }: { product: Product }) => (
+	<li {...track({ item: { product } })}>
+		<ProductCard product={product} />
+	</li>
+);
+```
+
+- **Server components** can't set data: render the element from a client component, e.g. a `<li>` around a server-rendered card passed as `children`.
+- **Before hydration** an element has no data, so it isn't tracked yet, clicks included.
+- **Every render** can pass new objects: equal data is ignored. Changed data, e.g. a new price, is viewed again, once per page.
+- **Keep it lean:** data is keyed and compared as JSON. Or pass a function, `track({ item: () => toItem(product) })`, built when first read; keep it stable (`useCallback`) when that's costly.
+- **Without data**, e.g. `track({ quickView: product && { product, variant } })` while closed, the element isn't tracked as one.
+- **Forgotten refs** leave an element untracked; in development, `ecommerce()` warns after 2 seconds.
+- **Own refs:** call both, e.g. `const { ref, ...quickView } = track({ quickView: item })` and `ref={(el) => { dialogRef.current = el; ref(el); }}`.
+- **Without a framework**, call the `ref` with the element: `track({ item: data }).ref(element)` sets the data and adds `item` to `data-track`, `track({ quickView: undefined }).ref(element)` removes both.
+
+### Promotions with products
+
+A promotion can contain product cards. What's tracked depends on whether they're inside a `list`:
+
+| Markup                                        | Views                                                                      | Click on a product                              |
+| --------------------------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------- |
+| `promotion` around `item` cards (recommended) | `promotionViewed` with the products in `items`                             | `promotionSelected` with that product as `item` |
+| `promotion` around a `list` with `item` cards | `promotionViewed` with `items: []`, and `itemsViewed` with the `promotion` | `itemSelected` with the `promotion`             |
+
+Clicks on other links inside are `promotionSelected`. Add the list only when the products should also be reported as a list.
+
+## Cart
+
+`createCartChanges<CartItem>({ storageKey })` from `@buildinams/core/tracking/cart` reports `addedToCart` and `removedFromCart` by comparing the carts the server confirms, so buttons, quantity pickers and drawers don't each track. Pass it every confirmed cart:
+
+```ts
+// Wherever a confirmed cart arrives: a server action's response, a store, a refetch.
+cartChanges.setCart({
+	id: cart.id,
+	currency: "EUR",
+	lines: cart.lines.map((line) => ({
+		id: line.id,
+		quantity: line.quantity,
+		price: line.unitPrice, // after discounts
+		item: { product: line.product, variant: line.variant },
+	})),
+});
+
+// No cart, e.g. before the first add or after checkout.
+cartChanges.setCart(null);
+```
+
+On Shopify, `toStorefrontCartSnapshot(cart)` from `@buildinams/core/analytics/shopify` turns a Storefront API cart into a `CartSnapshot<ShopifyStorefrontCartLine>`; use `ShopifyStorefrontCartLine` as the cart item and `toStorefrontCartProduct` in `shopifyMapping()`.
+
+| Change                     | Reports                                                |
+| -------------------------- | ------------------------------------------------------ |
+| A new line                 | `addedToCart` with its quantity                        |
+| A higher or lower quantity | `addedToCart` or `removedFromCart` with the difference |
+| A removed line             | `removedFromCart` with its quantity                    |
+| A swap, e.g. another size  | `removedFromCart`, then `addedToCart`                  |
+| A cart with another id     | `addedToCart` for all its lines                        |
+| `null`                     | Nothing                                                |
+
+- **One occurrence per kind and update**, with `value` as the sum of `price × quantity` of what changed.
+- **Lines are matched by `id`**, so use one that's stable while the line is in the cart.
+- **Confirmed carts only:** pass what the server returned, not optimistic state.
+- **The first cart is the starting point**, so a page loaded with a full cart tracks nothing, unless an earlier page stored a different one, e.g. after a form that adds and redirects.
+- **Once across tabs:** the last cart is kept in `localStorage` (`storageKey`, default `"analytics-cart"`). Change the key when your item's shape changes.
+- **Before the first `subscribe()`**, the last cart passed is held, and reported to every subscription made in the same task, e.g. when a child's effect runs before its parent subscribes.
+
+## Page views without `pageViews()`
+
+To track page views from the router instead of markup, track from a client component every page renders:
+
+```tsx
+"use client";
+
+import type { PageType } from "@buildinams/core/tracking/dom";
+
+export const PageView = ({ pageType }: { pageType: PageType }) => {
+	const pathname = usePathname();
+
+	React.useEffect(() => {
+		domWatcher.newPage();
+		analytics.track("pageViewed", { pageType });
+	}, [pathname, pageType]);
+
+	return null;
+};
+```
+
+- **Declare `pageViewed`** in the catalog yourself, e.g. with `payload: shape<{ pageType?: PageType }>()`, as the watcher's `events` only has it with `pageViews()`.
+- **`pathname` is a dependency**, as two product pages can share the component without remounting.
+- **`domWatcher.newPage()`** flushes the previous page's views and re-views what stays in view; leave it out without a markup watcher.
+- **Query strings:** add `useSearchParams()` to the dependencies and wrap `<PageView />` in `<Suspense>`.
+
+## Debugging
+
+- **Log what's reported:** `domWatcher.subscribe((event) => console.debug(event))`.
+- **See an element's data:** `$0[Symbol.for("@buildinams/core/tracking/dom")]` in the console, per type.
+- **An occurrence missing?** Nothing subscribes to its tracker, the element lacks its type or data, or a listener returned early for it or threw.

package/package.json

@@ -1,7 +1,8 @@
 {
 	"name": "@buildinams/core",
-	"version": "0.3.1",
+	"version": "0.4.0",
 	"type": "module",
+	"sideEffects": false,
 	"author": "Build in Amsterdam <development@buildinamsterdam.com> (https://www.buildinamsterdam.com/)",
 	"repository": {
 		"type": "git",
@@ -14,6 +15,7 @@
 		"build": "tsup",
 		"dev": "tsup --watch",
 		"lint": "eslint .",
+		"typecheck": "tsc --noEmit",
 		"test": "vitest watch",
 		"test:ci": "vitest run",
 		"lint:fix": "eslint . --fix"
@@ -25,6 +27,42 @@
 			"types": "./dist/index.d.ts",
 			"default": "./dist/index.js"
 		},
+		"./analytics": {
+			"types": "./dist/analytics/index.d.ts",
+			"default": "./dist/analytics/index.js"
+		},
+		"./analytics/google": {
+			"types": "./dist/analytics/google/index.d.ts",
+			"default": "./dist/analytics/google/index.js"
+		},
+		"./analytics/shopify": {
+			"types": "./dist/analytics/shopify/index.d.ts",
+			"default": "./dist/analytics/shopify/index.js"
+		},
+		"./consent": {
+			"types": "./dist/consent/index.d.ts",
+			"default": "./dist/consent/index.js"
+		},
+		"./consent/cookiebot": {
+			"types": "./dist/consent/cookiebot/index.d.ts",
+			"default": "./dist/consent/cookiebot/index.js"
+		},
+		"./consent/google": {
+			"types": "./dist/consent/google/index.d.ts",
+			"default": "./dist/consent/google/index.js"
+		},
+		"./consent/shopify": {
+			"types": "./dist/consent/shopify/index.d.ts",
+			"default": "./dist/consent/shopify/index.js"
+		},
+		"./consent/onetrust": {
+			"types": "./dist/consent/onetrust/index.d.ts",
+			"default": "./dist/consent/onetrust/index.js"
+		},
+		"./cookies": {
+			"types": "./dist/cookies/index.d.ts",
+			"default": "./dist/cookies/index.js"
+		},
 		"./navigation": {
 			"types": "./dist/navigation/index.d.ts",
 			"default": "./dist/navigation/index.js"
@@ -36,6 +74,14 @@
 		"./store": {
 			"types": "./dist/store/index.d.ts",
 			"default": "./dist/store/index.js"
+		},
+		"./tracking/cart": {
+			"types": "./dist/tracking/cart/index.d.ts",
+			"default": "./dist/tracking/cart/index.js"
+		},
+		"./tracking/dom": {
+			"types": "./dist/tracking/dom/index.d.ts",
+			"default": "./dist/tracking/dom/index.js"
 		}
 	},
 	"typesVersions": {
@@ -43,6 +89,33 @@
 			"*": [
 				"./dist/index.d.ts"
 			],
+			"./analytics": [
+				"./dist/analytics/index.d.ts"
+			],
+			"./analytics/google": [
+				"./dist/analytics/google/index.d.ts"
+			],
+			"./analytics/shopify": [
+				"./dist/analytics/shopify/index.d.ts"
+			],
+			"./consent": [
+				"./dist/consent/index.d.ts"
+			],
+			"./consent/cookiebot": [
+				"./dist/consent/cookiebot/index.d.ts"
+			],
+			"./consent/onetrust": [
+				"./dist/consent/onetrust/index.d.ts"
+			],
+			"./consent/google": [
+				"./dist/consent/google/index.d.ts"
+			],
+			"./consent/shopify": [
+				"./dist/consent/shopify/index.d.ts"
+			],
+			"./cookies": [
+				"./dist/cookies/index.d.ts"
+			],
 			"./navigation": [
 				"./dist/navigation/index.d.ts"
 			],
@@ -51,11 +124,18 @@
 			],
 			"./store": [
 				"./dist/store/index.d.ts"
+			],
+			"./tracking/cart": [
+				"./dist/tracking/cart/index.d.ts"
+			],
+			"./tracking/dom": [
+				"./dist/tracking/dom/index.d.ts"
 			]
 		}
 	},
 	"files": [
 		"dist",
+		"docs",
 		"README.md"
 	],
 	"publishConfig": {
@@ -64,9 +144,10 @@
 	},
 	"devDependencies": {
 		"@buildinams/lint": "^0.4.0",
+		"next": "^16.4.5",
 		"tsup": "^8.0.1",
 		"typescript": "^5.4.5",
-		"vitest": "^3.2.4"
+		"vitest": "^5.1.0"
 	},
 	"dependencies": {
 		"clsx": "^2.1.1"

package/dist/chunk-5KDGGGVO.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/schema/schema.ts","../src/schema/string-schema.ts","../src/schema/href-schema.ts"],"names":[],"mappings":";AAkGO,IAAM,YAAA,GAAe,CAK3B,QAAA,MACmD;AAAA,EACnD,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;;;AC9FO,IAAM,kBAAA,GAAqB,CACjC,QAAA,KAC4C;AAC5C,EAAA,MAAM,SAAS,YAAA,CAA+C;AAAA,IAC7D,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;;;ACKO,IAAM,aAAa,kBAAA,CASxB;AAAA,EACD,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,IAAI,CAAC,KAAA,CAAM,YAAA,EAAc,OAAO,KAAA,CAAM,QAAA;AACtC,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-5KDGGGVO.js","sourcesContent":["/**\n * Defines the schema for parsing and stringifying states to and from primitive values.\n *\n * The `Schema` type is a generic type that takes:\n * - `State`: A state object type.\n * - `Serialized`: The raw value type\n * - `SerializableState?`: (optional) A (partial) state object type that can be used for serialization. Defaults to `State` if not provided.\n *\n * It returns the following methods:\n * - `parse`: A function that takes a raw value and returns the corresponding state object.\n * - `serialize`: A function that takes a (serializable) state object and returns a raw value that represents the given state.\n * - `parserialize`: A function that takes a raw value and a reducer function - it returns a new raw value that represents the reduced state.\n *\n * @see createSchema for a helper function to create a `Schema` from simpler parsing and serializing functions.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type Schema<State = any, Serialized = any, SerializableState = State> = {\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: SerializableState) => 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) => SerializableState,\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 * A utility type to extract the serializable state shape from a given `Schema`.\n */\nexport type SchemaSerializableState<T extends Schema> =\n\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\tT extends Schema<any, 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 methods:\n * - `parse`: A method that takes a serialized value and returns the corresponding state object.\n * - `serialize`: A method that takes a state object and returns a serialized value that represents the given state.\n *\n * The `parserialize` method is automatically implemented based on the provided `parse` and `serialize` methods, allowing you to compute a new serialized value based on an existing serialized value and a reducer function for the state.\n *\n * @example\n * ```ts\n * import { createSchema } from \"@buildinams/core/schema\";\n *\n * const numberSchema = createSchema<\n *   number, // State\n *   string // Serialized\n * >({\n *   parse: (value) => parseInt(value, 10),\n *   serialize: (state) => state.toString(),\n * });\n *\n * const result = numberSchema.parserialize(\"42\", (state) => state + 1);\n * console.log(result); // \"43\"\n * ```\n *\n * @example\n * ```ts\n * import { createSchema } from \"@buildinams/core/schema\";\n *\n * const hrefSchema: createSchema<\n *   { pathname: string, searchParams: URLSearchParams },\n *   string,\n *   { pathname: string, searchParams?: URLSearchParams } // SerializableState allows to define different state used for serialization, in this case making searchParams optional to allow for more flexible stringification logic\n * >({\n *  parse: (href) => {\n *    const [pathname = \"\", search = \"\"] = href.split(\"?\");\n *    return {\n *     pathname,\n *     searchParams: new URLSearchParams(search),\n *    };\n *  },\n *  serialize: (serializableState) => {\n *    if (!serializableState.searchParams) return serializableState.pathname;\n *    const paramsString = serializableState.searchParams.toString();\n *    return serializableState.pathname + (paramsString ? `?${paramsString}` : \"\");\n *  },\n * })\n * ```\n */\nexport const createSchema = <\n\tState = never,\n\tSerialized = never,\n\tSerializableState = State,\n>(\n\ttemplate: Omit<Schema<State, Serialized, SerializableState>, \"parserialize\">,\n): Schema<State, Serialized, SerializableState> => ({\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, SerializableState = State> = {\n\tparse: Schema<State, string, SerializableState>[\"parse\"];\n\tstringify: Schema<State, string, SerializableState>[\"serialize\"];\n\tparseStringify: Schema<State, string, SerializableState>[\"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 = <State = never, SerializableState = State>(\n\ttemplate: Omit<StringSchema<State, SerializableState>, \"parseStringify\">,\n): StringSchema<State, SerializableState> => {\n\tconst schema = createSchema<State, string, SerializableState>({\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\") || \"1\", 10),\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 *\n *    // note that `searchParams` are optional for serialization\n *    return hrefSchema.stringify({ pathname, searchParams });\n *   }\n * });\n * ```\n */\nexport const hrefSchema = createStringSchema<\n\t{\n\t\tpathname: string;\n\t\tsearchParams: URLSearchParams;\n\t},\n\t{\n\t\tpathname: string;\n\t\tsearchParams?: URLSearchParams;\n\t}\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\tif (!state.searchParams) return state.pathname;\n\t\tconst paramsString = state.searchParams.toString();\n\t\treturn state.pathname + (paramsString ? `?${paramsString}` : \"\");\n\t},\n});\n"]}

package/dist/chunk-SIU7SKJK.js

@@ -1,139 +0,0 @@
-import clsx from 'clsx';
-
-// src/config/index.ts
-var IS_DEVELOPMENT = process.env.NODE_ENV === "development";
-var IS_BUILD = process.env.NODE_ENV === "production";
-var IS_IN_BROWSER = (() => {
-  try {
-    return !!window && "document" in window && !!window.document?.createElement;
-  } catch {
-    return false;
-  }
-})();
-
-// src/functions/apply-state.ts
-function isUpdater(argument) {
-  return typeof argument === "function";
-}
-function isLazyValue(value) {
-  return typeof value === "function";
-}
-function applyState(argument, currentValue) {
-  if (isUpdater(argument)) {
-    const value = isLazyValue(currentValue) ? currentValue() : currentValue;
-    return argument(value);
-  }
-  return argument;
-}
-
-// src/functions/default-value.ts
-function defaultValue(...values) {
-  for (const value of values) {
-    if (value !== void 0) return value;
-  }
-  return void 0;
-}
-
-// src/functions/identity.ts
-function identity(value) {
-  return value;
-}
-
-// src/functions/math.ts
-var wrap = (value, [min, max]) => {
-  const range = max - min + 1;
-  return ((value - min) % range + range) % range + min;
-};
-var clamp = (value, [min, max]) => {
-  return Math.min(Math.max(value, min), max);
-};
-var transform = (value, originRange, targetRange) => {
-  const [oMin, oMax] = originRange;
-  const [tMin, tMax] = targetRange;
-  const ratio = (value - oMin) / (oMax - oMin);
-  const transformedValue = tMin + ratio * (tMax - tMin);
-  return transformedValue;
-};
-var round = (value, decimalPlaces = 0) => {
-  const factor = Math.pow(10, decimalPlaces);
-  return Math.round((value + Number.EPSILON) * factor) / factor;
-};
-var mergeClassNames = (...classNames) => {
-  try {
-    return clsx(...classNames);
-  } catch (error) {
-    throw new Error(
-      "mergeClassNames: Invalid input provided. Ensure all class names are strings, undefined, or null."
-    );
-  }
-};
-
-// src/functions/platform.ts
-var isTouchDevice = () => {
-  return IS_IN_BROWSER && !!navigator.maxTouchPoints;
-};
-var isApple = () => {
-  if (!IS_IN_BROWSER) return false;
-  return /mac|iphone|ipad|ipod/i.test(navigator.platform);
-};
-var isMac = () => {
-  return IS_IN_BROWSER && navigator.platform.startsWith("Mac") && !isTouchDevice();
-};
-
-// src/functions/remove-undefined-values.ts
-function removeUndefinedValues(obj) {
-  const result = {};
-  for (const key in obj) {
-    if (obj[key] !== void 0) {
-      result[key] = obj[key];
-    }
-  }
-  return result;
-}
-
-// src/functions/shallow-equal.ts
-function shallowEqual(a, b) {
-  if (a === b) return true;
-  if (!a) return false;
-  if (!b) return false;
-  if (typeof a !== "object") return false;
-  if (typeof b !== "object") return false;
-  const aKeys = Object.keys(a);
-  const bKeys = Object.keys(b);
-  const { length } = aKeys;
-  if (bKeys.length !== length) return false;
-  for (const key of aKeys) {
-    if (a[key] !== b[key]) {
-      return false;
-    }
-  }
-  return true;
-}
-
-// src/functions/type-guards.ts
-var notEmpty = (value) => value !== null && value !== void 0;
-var isHTMLElement = (node) => node instanceof HTMLElement;
-var isInArray = (item, array) => array.includes(item);
-var isObject = (object) => {
-  try {
-    return typeof object === "object" && object !== null && !Array.isArray(object);
-  } catch {
-    throw new Error("isObject: Invalid input");
-  }
-};
-var isTruthy = (value) => !!value;
-function invariant(condition, message) {
-  if (condition) return;
-  if (typeof message !== "string") throw new Error("Invariant failed");
-  throw new Error(message);
-}
-var hasOwnProperty = (object, prop) => {
-  if (typeof Object.hasOwn === "function") {
-    return Object.hasOwn(object, prop);
-  }
-  return Object.prototype.hasOwnProperty.call(object, prop);
-};
-
-export { IS_BUILD, IS_DEVELOPMENT, IS_IN_BROWSER, applyState, clamp, defaultValue, hasOwnProperty, identity, invariant, isApple, isHTMLElement, isInArray, isMac, isObject, isTouchDevice, isTruthy, mergeClassNames, notEmpty, removeUndefinedValues, round, shallowEqual, transform, wrap };
-//# sourceMappingURL=chunk-SIU7SKJK.js.map
-//# sourceMappingURL=chunk-SIU7SKJK.js.map

package/dist/chunk-SIU7SKJK.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/config/index.ts","../src/functions/apply-state.ts","../src/functions/default-value.ts","../src/functions/identity.ts","../src/functions/math.ts","../src/functions/merge-class-names.ts","../src/functions/platform.ts","../src/functions/remove-undefined-values.ts","../src/functions/shallow-equal.ts","../src/functions/type-guards.ts"],"names":[],"mappings":"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","file":"chunk-SIU7SKJK.js","sourcesContent":["export const IS_DEVELOPMENT = process.env.NODE_ENV === \"development\";\nexport const IS_BUILD = process.env.NODE_ENV === \"production\";\n\nexport const IS_IN_BROWSER = (() => {\n\ttry {\n\t\treturn !!window && \"document\" in window && !!window.document?.createElement;\n\t} catch {\n\t\treturn false;\n\t}\n})();\n","/* eslint-disable @typescript-eslint/no-explicit-any */\n\nimport { BivariantCallback, SetStateAction } from \"src/types\";\n\nfunction isUpdater<T>(\n\targument: SetStateAction<T>,\n): argument is BivariantCallback<(prevState: T) => T> {\n\treturn typeof argument === \"function\";\n}\n\nfunction isLazyValue<T>(value: any): value is () => T {\n\treturn typeof value === \"function\";\n}\n\n/**\n * Receives a `setState` argument and calls it with `currentValue` if it's a\n * function. Otherwise return the argument as the new value.\n * @example\n * applyState((value) => value + 1, 1); // 2\n * applyState(2, 1); // 2\n */\nexport function applyState<T>(\n\targument: SetStateAction<T>,\n\tcurrentValue: T | (() => T),\n) {\n\tif (isUpdater(argument)) {\n\t\tconst value = isLazyValue(currentValue) ? currentValue() : currentValue;\n\t\treturn argument(value);\n\t}\n\treturn argument;\n}\n","/* eslint-disable @typescript-eslint/no-explicit-any */\n/**\n * Returns the first value that is not `undefined`.\n */\nexport function defaultValue<T extends readonly any[]>(\n\t...values: T\n): DefaultValue<T>;\n\nexport function defaultValue(...values: unknown[]) {\n\tfor (const value of values) {\n\t\tif (value !== undefined) return value;\n\t}\n\treturn undefined;\n}\n\ntype DefaultValue<T extends readonly any[], Other = never> = T extends [\n\tinfer Head,\n\t...infer Rest,\n]\n\t? Rest extends []\n\t\t? T[number] | Other\n\t\t: undefined extends Head\n\t\t\t? DefaultValue<Rest, Exclude<Other | Head, undefined>>\n\t\t\t: Exclude<T[number], undefined>\n\t: never;\n","/**\n * Returns the same argument.\n */\nexport function identity<T>(value: T) {\n\treturn value;\n}\n","/**\n * Wraps a number within a specified range.\n * @param value - The number to wrap.\n * @param min - The minimum value of the range (inclusive).\n * @param max - The maximum value of the range (inclusive).\n * @returns The wrapped number within the range [min, max].\n *\n * @example\n * wrap(5, [0, 3]); // Returns 1\n * wrap(-1, [0, 3]); // Returns 2\n * wrap(-3, [0, 3]); // Returns 1\n * wrap(7, [0, 3]); // Returns 3\n */\nexport const wrap = (value: number, [min, max]: [min: number, max: number]) => {\n\tconst range = max - min + 1;\n\treturn ((((value - min) % range) + range) % range) + min;\n};\n\n/**\n * Limits a value between a specified range.\n * @param value - The number to limit.\n * @param min - The minimum value of the range (inclusive).\n * @param max - The maximum value of the range (inclusive).\n * @returns The wrapped number within the range [min, max].\n *\n * @example\n * clamp(2, [0, 3]); // Returns 2\n * clamp(5, [0, 3]); // Returns 3\n * clamp(-1, [0, 3]); // Returns 0\n * clamp(-3, [0, 3]); // Returns 0\n * clamp(7, [0, 3]); // Returns 3\n */\nexport const clamp = (\n\tvalue: number,\n\t[min, max]: [min: number, max: number],\n) => {\n\treturn Math.min(Math.max(value, min), max);\n};\n\n/**\n * Maps a number from one range to another.\n * @param value The number to map.\n * @param originRange The original range of the number.\n * @param targetRange The target range to map the number to.\n * @returns The mapped number within the target range.\n *\n * @example\n * transform(5, [0, 10], [0, 100]); // Returns 50\n * transform(0.5, [0, 1], [0, 10]); // Returns 5\n * transform(-5, [-10, 0], [0, 100]); // Returns 50\n */\nexport const transform = (\n\tvalue: number,\n\toriginRange: [number, number],\n\ttargetRange: [number, number],\n) => {\n\tconst [oMin, oMax] = originRange;\n\tconst [tMin, tMax] = targetRange;\n\n\tconst ratio = (value - oMin) / (oMax - oMin);\n\tconst transformedValue = tMin + ratio * (tMax - tMin);\n\n\treturn transformedValue;\n};\n\n/**\n * Rounds a number to a specified number of decimal places.\n * @param value - The number to round.\n * @param decimalPlaces - The number of decimal places to round to. (default is 0)\n * @returns The rounded number.\n */\nexport const round = (value: number, decimalPlaces: number = 0) => {\n\tconst factor = Math.pow(10, decimalPlaces);\n\treturn Math.round((value + Number.EPSILON) * factor) / factor;\n};\n","import clsx from \"clsx\";\n\nconst mergeClassNames = (...classNames: clsx.ClassValue[]) => {\n\ttry {\n\t\treturn clsx(...classNames);\n\t} catch (error) {\n\t\tthrow new Error(\n\t\t\t\"mergeClassNames: Invalid input provided. Ensure all class names are strings, undefined, or null.\",\n\t\t);\n\t}\n};\n\n// Name isn't very memorable, so we export it in this file to alias it\nexport { mergeClassNames };\n","import { IS_IN_BROWSER } from \"src/config\";\n\n/**\n * Detects if the device has touch capabilities.\n */\nexport const isTouchDevice = () => {\n\treturn IS_IN_BROWSER && !!navigator.maxTouchPoints;\n};\n\n/**\n * Detects Apple device.\n */\nexport const isApple = () => {\n\tif (!IS_IN_BROWSER) return false;\n\treturn /mac|iphone|ipad|ipod/i.test(navigator.platform);\n};\n\n/**\n * Detects Mac computer.\n */\nexport const isMac = () => {\n\treturn (\n\t\tIS_IN_BROWSER && navigator.platform.startsWith(\"Mac\") && !isTouchDevice()\n\t);\n};\n","import { AnyObject } from \"../types\";\n\n/**\n * Removes undefined values from an object.\n */\nexport function removeUndefinedValues<T extends AnyObject>(obj: T) {\n\tconst result = {} as T;\n\tfor (const key in obj) {\n\t\tif (obj[key] !== undefined) {\n\t\t\tresult[key] = obj[key];\n\t\t}\n\t}\n\treturn result;\n}\n","import { AnyObject } from \"src/types\";\n\n/**\n * Compares two objects.\n * @example\n * shallowEqual({ a: \"a\" }, {}); // false\n * shallowEqual({ a: \"a\" }, { b: \"b\" }); // false\n * shallowEqual({ a: \"a\" }, { a: \"a\" }); // true\n * shallowEqual({ a: \"a\" }, { a: \"a\", b: \"b\" }); // false\n */\nexport function shallowEqual(a?: AnyObject, b?: AnyObject) {\n\tif (a === b) return true;\n\tif (!a) return false;\n\tif (!b) return false;\n\tif (typeof a !== \"object\") return false;\n\tif (typeof b !== \"object\") return false;\n\n\tconst aKeys = Object.keys(a);\n\tconst bKeys = Object.keys(b);\n\tconst { length } = aKeys;\n\n\tif (bKeys.length !== length) return false;\n\n\tfor (const key of aKeys) {\n\t\tif (a[key] !== b[key]) {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\treturn true;\n}\n","import { AnyObject } from \"src/types\";\n\n/**\n * @function notEmpty\n * @description Checks if a value is not null or undefined.\n *\n * @param value - The value to check.\n * @returns Whether the value is not null or undefined.\n *\n * @example\n * ```ts\n * notEmpty(\"Hello\"); // true\n * notEmpty(null); // false\n * notEmpty(undefined); // false\n * ```\n */\nexport const notEmpty = <TValue>(\n\tvalue: TValue | null | undefined,\n): value is TValue => value !== null && value !== undefined;\n\n/**\n * @function isHTMLElement\n * @description Checks if a value is an instance of HTMLElement.\n *\n * @param node - The value to check.\n * @returns Whether the value is an instance of HTMLElement.\n *\n * @example\n * ```ts\n * isHTMLElement(document.querySelector('body')); // true\n * isHTMLElement({}); // false\n * ```\n */\n\nexport const isHTMLElement = (node: unknown): node is HTMLElement =>\n\tnode instanceof HTMLElement;\n\n/**\n * @function isInArray\n * @description Typesafe check if an item is in an array without being explicit about const types\n *\n * @param item - The item to check.\n * @param array - The array to check against.\n *\n * @returns Whether the item is in the array.\n *\n * @example\n * ```ts\n * // Default situation in TS:\n * const arr = ['hello', 'world'] as const;\n *\n * let someString = 'something';\n *\n * arr.includes(someString); // Argument of type 'string' is not assignable to parameter of type '\"hello\" | \"world\"'\n *\n * // Using isInArray:\n * const arr = ['hello', 'world'] as const;\n *\n * let someString = 'something';\n *\n * isInArray(someString, arr); // false, but no type error\n * ```\n */\nexport const isInArray = <T, A extends T>(\n\titem: T,\n\tarray: ReadonlyArray<A>,\n): item is A => array.includes(item as A);\n\n/**\n * @function isObject\n * @description Checks if a value is an object (excluding arrays).\n *\n * @param object - The value to check.\n * @returns Whether the value is truthy.\n *\n * @example\n * ```ts\n * isObject({ hello: world }); // true\n * isObject({}); // true\n * isObject([]); // false\n * isObject(\"\"); // false\n * isObject(null); // false\n * ```\n */\nexport const isObject = (\n\tobject: unknown,\n): object is Record<string, unknown> => {\n\ttry {\n\t\treturn (\n\t\t\ttypeof object === \"object\" && object !== null && !Array.isArray(object)\n\t\t);\n\t} catch {\n\t\tthrow new Error(\"isObject: Invalid input\");\n\t}\n};\n\n/**\n * @function isTruthy\n * @description Checks if a value is truthy.\n *\n * @param value - The value to check.\n * @returns Whether the value is truthy.\n *\n * @example\n * ```ts\n * isTruthy(\"foo\"); // true\n * isTruthy(1); // true\n * isTruthy(0); // false\n * isTruthy(\"\"); // false\n * ```\n *\n */\nexport const isTruthy = <T>(value?: T | undefined | null | false): value is T =>\n\t!!value;\n\n/**\n * Asserts that a condition is true, otherwise throws an error.\n * @example\n * invariant(\n *   condition,\n *   process.env.NODE_ENV !== \"production\" && \"Invariant failed\"\n * );\n */\n// assert functions need to be an explicit function(){}\nexport function invariant(\n\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\tcondition: any,\n\tmessage?: string | boolean,\n): asserts condition {\n\tif (condition) return;\n\tif (typeof message !== \"string\") throw new Error(\"Invariant failed\");\n\tthrow new Error(message);\n}\n\n/**\n * Checks if an object has a property as its own (not inherited) property.\n * @example\n * hasOwnProperty({ a: \"a\" }, \"a\"); // true\n * hasOwnProperty({ a: \"a\" }, \"b\"); // false\n * hasOwnProperty(Object.create({ a: \"a\" }), \"a\"); // false\n */\nexport const hasOwnProperty = <T extends AnyObject>(\n\tobject: T,\n\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\tprop: keyof any,\n): prop is keyof T => {\n\tif (typeof Object.hasOwn === \"function\") {\n\t\treturn Object.hasOwn(object, prop);\n\t}\n\treturn Object.prototype.hasOwnProperty.call(object, prop);\n};\n"]}