@escape-game-over/atlas 0.1.115 → 0.1.117

package/src/jsonld/article.ts

@@ -2,7 +2,7 @@ import type { IsoDate } from "../types.ts";
 import type { HttpsUrl } from "../url.ts";
 import { warn } from "../warn.ts";
 import type { BusinessId, OrganizationId } from "./ids.ts";
-import { type JsonLdNode, oneOrMany } from "./node.ts";
+import { type JsonLdNode, listed, oneOrMany, reference } from "./node.ts";
 
 export interface ArticleInput {
     /**
@@ -137,29 +137,19 @@ export function article(item: ArticleInput): JsonLdNode {
     return {
         "@type": item.kind ?? "Article",
         headline: item.headline,
-        ...(item.description === undefined
-            ? {}
-            : { description: item.description }),
+        description: item.description,
         // Not `url`: an article is a thing, and this is the page it is *on*.
         mainEntityOfPage: item.url,
         datePublished: item.datePublished,
-        ...(item.dateModified === undefined
-            ? {}
-            : { dateModified: item.dateModified }),
+        dateModified: item.dateModified,
         // Passed through in the shape it arrived in, bar a list of one — which
         // is `schemaType`'s rule applied to a second field: writing `[x]` is
         // fine, emitting it reads as a bug.
-        ...(item.image === undefined ? {} : { image: oneOrMany(item.image) }),
-        ...(item.author === undefined
-            ? {}
-            : { author: { "@id": item.author } }),
-        ...(item.publisher === undefined
-            ? {}
-            : { publisher: { "@id": item.publisher } }),
+        image: item.image === undefined ? undefined : oneOrMany(item.image),
+        author: reference(item.author),
+        publisher: reference(item.publisher),
         // An empty list is not a set of no keywords, it is a field saying
         // nothing — so it is left out, as every optional here is.
-        ...(item.tags === undefined || item.tags.length === 0
-            ? {}
-            : { keywords: item.tags }),
+        keywords: listed(item.tags),
     };
 }

package/src/jsonld/business.ts

@@ -10,7 +10,13 @@ import type { ImageAsset } from "../image.ts";
 import type { NonEmpty } from "../types.ts";
 import { absoluteUrl, type HttpsUrl } from "../url.ts";
 import { businessId, type OrganizationId } from "./ids.ts";
-import { alternateName, type JsonLdNode, schemaType } from "./node.ts";
+import {
+    alternateName,
+    type JsonLdNode,
+    listed,
+    reference,
+    schemaType,
+} from "./node.ts";
 import { geoCoordinates, openingHours, postalAddress } from "./place.ts";
 
 export interface LocalBusinessInput {
@@ -173,34 +179,27 @@ export function localBusiness(business: LocalBusinessInput): JsonLdNode {
         "@type": schemaType(business.type ?? "LocalBusiness"),
         "@id": businessId(business.url, business.location),
         name: business.name,
-        ...alternateName(business.name, business.alternateName),
+        alternateName: alternateName(business.name, business.alternateName),
         url: business.url,
         address: postalAddress(business.address),
-        ...(business.geo === undefined
-            ? {}
-            : { geo: geoCoordinates(business.geo) }),
-        ...(business.priceRange === undefined
-            ? {}
-            : { priceRange: business.priceRange }),
-        ...(business.image === undefined || business.image.length === 0
-            ? {}
-            : {
-                  image: business.image.map((photo) =>
-                      absoluteUrl(business.url, photo.src, "venue photo")
-                  ),
-              }),
-        ...(business.telephone === undefined
-            ? {}
-            : { telephone: e164(business.telephone) }),
-        ...(business.email === undefined ? {} : { email: business.email }),
-        ...(business.hours === undefined
-            ? {}
-            : { openingHoursSpecification: openingHours(business.hours) }),
-        ...(business.sameAs === undefined ? {} : { sameAs: business.sameAs }),
-        ...(business.parentOrganization === undefined
-            ? {}
-            : {
-                  parentOrganization: { "@id": business.parentOrganization },
-              }),
+        geo:
+            business.geo === undefined
+                ? undefined
+                : geoCoordinates(business.geo),
+        priceRange: business.priceRange,
+        image: listed(business.image)?.map((photo) =>
+            absoluteUrl(business.url, photo.src, "venue photo")
+        ),
+        telephone:
+            business.telephone === undefined
+                ? undefined
+                : e164(business.telephone),
+        email: business.email,
+        openingHoursSpecification:
+            business.hours === undefined
+                ? undefined
+                : openingHours(business.hours),
+        sameAs: business.sameAs,
+        parentOrganization: reference(business.parentOrganization),
     };
 }

package/src/jsonld/creative-work.ts

@@ -1,7 +1,7 @@
 import type { Quantity } from "../money.ts";
 import type { HttpsUrl } from "../url.ts";
 import type { BusinessId, OrganizationId } from "./ids.ts";
-import { type JsonLdNode, schemaType } from "./node.ts";
+import { type JsonLdNode, listed, reference, schemaType } from "./node.ts";
 import { quantitativeValue } from "./quantity.ts";
 
 /**
@@ -92,19 +92,11 @@ export function creativeWork(work: CreativeWorkInput): JsonLdNode {
         "@type": schemaType(["CreativeWork", ...(work.alsoA ?? [])]),
         name: work.name,
         url: work.url,
-        ...(work.description === undefined
-            ? {}
-            : { description: work.description }),
-        ...(work.image === undefined ? {} : { image: work.image }),
-        ...(work.genre === undefined || work.genre.length === 0
-            ? {}
-            : { genre: work.genre }),
-        ...(work.creator === undefined
-            ? {}
-            : { creator: { "@id": work.creator } }),
-        ...(work.properties === undefined || work.properties.length === 0
-            ? {}
-            : { additionalProperty: work.properties.map(propertyValue) }),
+        description: work.description,
+        image: work.image,
+        genre: listed(work.genre),
+        creator: reference(work.creator),
+        additionalProperty: listed(work.properties)?.map(propertyValue),
     };
 }
 
@@ -114,12 +106,8 @@ function propertyValue(property: CreativeWorkProperty): JsonLdNode {
         name: property.name,
         value: {
             ...quantitativeValue(property.value),
-            ...(property.unitCode === undefined
-                ? {}
-                : { unitCode: property.unitCode }),
-            ...(property.unitText === undefined
-                ? {}
-                : { unitText: property.unitText }),
+            unitCode: property.unitCode,
+            unitText: property.unitText,
         },
     };
 }

package/src/jsonld/node.ts

@@ -7,7 +7,13 @@
 
 import { literal } from "../analytics/tags.ts";
 
-/** A node in the graph. Deliberately loose: `@type` is what a consumer varies. */
+/**
+ * A node in the graph. Deliberately loose: `@type` is what a consumer varies.
+ *
+ * An optional field it lacks is written as `undefined`, never branched around
+ * with a conditional spread: `serializeJsonLd` goes through JSON, which drops
+ * it, so the published node has no such key either way.
+ */
 export interface JsonLdNode {
     readonly "@type": string | readonly string[];
     readonly [key: string]: unknown;
@@ -47,8 +53,8 @@ export function schemaType(
  * engine reads it as *another* name and a repeat of the first one is not that:
  * it widens nothing and is one more string to reconcile. Decided here rather
  * than by the caller — three nodes take the field, the rule is the same on all
- * of them, and a project asked to write `name === alt ? {} : { alt }` at each
- * one is being handed lib's rule to enforce by hand.
+ * of them, and a project asked to write `alt === name ? undefined : alt` at
+ * each one is being handed lib's rule to enforce by hand.
  *
  * Which makes `alternateName: brand.name` safe to pass unconditionally: a venue
  * whose name already *is* the brand's simply emits nothing.
@@ -56,10 +62,34 @@ export function schemaType(
 export function alternateName(
     name: string,
     alternate: string | undefined
-): { readonly alternateName?: string } {
-    return alternate === undefined || alternate === name
-        ? {}
-        : { alternateName: alternate };
+): string | undefined {
+    return alternate === name ? undefined : alternate;
+}
+
+/**
+ * A pointer to a node published elsewhere in the graph, or nothing.
+ *
+ * Every field built from it is optional, and an `undefined` field is dropped
+ * when the graph is serialised: so a node can write `author:
+ * reference(item.author)` without a branch.
+ */
+export function reference<Id extends string>(
+    id: Id | undefined
+): { readonly "@id": Id } | undefined {
+    return id === undefined ? undefined : { "@id": id };
+}
+
+/**
+ * A list, or nothing when it is empty.
+ *
+ * An empty list is not a set of nothing, it is a field saying nothing — a
+ * claim to have been asked and had no answer — so it is left out like any
+ * other absent field.
+ */
+export function listed<T>(
+    list: readonly T[] | undefined
+): readonly T[] | undefined {
+    return list === undefined || list.length === 0 ? undefined : list;
 }
 
 /** The graph, serialised for a `<script type="application/ld+json">`. */

package/src/jsonld/organization.ts

@@ -8,7 +8,7 @@ import type { ImageAsset } from "../image.ts";
 import type { IsoDate } from "../types.ts";
 import { absoluteUrl, type HttpsUrl, joinUrl, type UrlPath } from "../url.ts";
 import { organizationId } from "./ids.ts";
-import { alternateName, type JsonLdNode } from "./node.ts";
+import { alternateName, type JsonLdNode, listed } from "./node.ts";
 import { postalAddress } from "./place.ts";
 
 export interface OrganizationInput {
@@ -172,36 +172,27 @@ export function organization(brand: OrganizationInput): JsonLdNode {
         "@id": organizationId(brand.url),
         name: brand.name,
         url: brand.url,
-        ...alternateName(brand.name, brand.alternateName),
-        ...(brand.description === undefined
-            ? {}
-            : { description: brand.description }),
-        ...(brand.foundingDate === undefined
-            ? {}
-            : { foundingDate: brand.foundingDate }),
-        ...(brand.logo === undefined
-            ? {}
-            : { logo: joinUrl(brand.url, brand.logo) }),
-        ...(brand.image === undefined || brand.image.length === 0
-            ? {}
-            : {
-                  image: brand.image.map((photo) =>
-                      absoluteUrl(brand.url, photo.src, "organization photo")
-                  ),
-              }),
-        ...(brand.legalName === undefined
-            ? {}
-            : { legalName: brand.legalName }),
-        ...(brand.vatID === undefined ? {} : { vatID: brand.vatID }),
+        alternateName: alternateName(brand.name, brand.alternateName),
+        description: brand.description,
+        foundingDate: brand.foundingDate,
+        logo:
+            brand.logo === undefined
+                ? undefined
+                : joinUrl(brand.url, brand.logo),
+        image: listed(brand.image)?.map((photo) =>
+            absoluteUrl(brand.url, photo.src, "organization photo")
+        ),
+        legalName: brand.legalName,
+        vatID: brand.vatID,
         // E.164, as on the business: the only form that identifies a number
         // unambiguously enough to match a company against a listing.
-        ...(brand.telephone === undefined
-            ? {}
-            : { telephone: e164(brand.telephone) }),
-        ...(brand.email === undefined ? {} : { email: brand.email }),
-        ...(brand.sameAs === undefined ? {} : { sameAs: brand.sameAs }),
-        ...(brand.address === undefined
-            ? {}
-            : { address: postalAddress(brand.address) }),
+        telephone:
+            brand.telephone === undefined ? undefined : e164(brand.telephone),
+        email: brand.email,
+        sameAs: brand.sameAs,
+        address:
+            brand.address === undefined
+                ? undefined
+                : postalAddress(brand.address),
     };
 }

package/src/jsonld/place.ts

@@ -37,13 +37,9 @@ export function postalAddress(address: PostalAddress): JsonLdNode {
         "@type": "PostalAddress",
         streetAddress: address.street,
         addressLocality: address.locality,
-        ...(address.postalCode === undefined
-            ? {}
-            : { postalCode: address.postalCode }),
+        postalCode: address.postalCode,
         addressCountry: address.country,
-        ...(address.region === undefined
-            ? {}
-            : { addressRegion: address.region }),
+        addressRegion: address.region,
     };
 }
 

package/src/jsonld/product.ts

@@ -11,7 +11,7 @@ import {
 import type { NonEmpty } from "../types.ts";
 import type { HttpsUrl } from "../url.ts";
 import type { BusinessId, OrganizationId } from "./ids.ts";
-import { type JsonLdNode, schemaType } from "./node.ts";
+import { type JsonLdNode, reference, schemaType } from "./node.ts";
 import { quantitativeValue } from "./quantity.ts";
 
 export interface ProductInput {
@@ -91,7 +91,7 @@ export function product(item: ProductInput): JsonLdNode {
         name: item.name,
         description: item.description,
         url: item.url,
-        ...(item.image === undefined ? {} : { image: item.image }),
+        image: item.image,
         offers: offersFor(item),
     };
 }
@@ -116,30 +116,24 @@ function offerFor(
         "@type": "Offer",
         // An `Offer` is a `Thing`, so it can carry a `name`; it is what tells
         // the adults' price from the children's.
-        ...(name === undefined ? {} : { name }),
+        name,
         price: amount,
         priceCurrency: item.price.currency,
         availability: "https://schema.org/InStock",
         url: item.url,
-        ...(band === undefined
-            ? {}
-            : {
-                  // What makes two prices a table rather than a contradiction:
-                  // each one says the quantity it applies at.
-                  //
-                  // The quantity is passed as written, not through `tierRange`:
-                  // the two take the same `number | { min, max }`, and widening
-                  // first would publish a band of one as `minValue: 2,
-                  // maxValue: 2` — a range across a single size, where `value:
-                  // 2` is the same claim said plainly.
-                  eligibleQuantity: {
-                      ...quantitativeValue(band.quantity),
-                      ...(unit === undefined ? {} : { unitText: unit }),
-                  },
-              }),
-        ...(item.seller === undefined
-            ? {}
-            : { seller: { "@id": item.seller } }),
+        // What makes two prices a table rather than a contradiction:
+        // each one says the quantity it applies at.
+        //
+        // The quantity is passed as written, not through `tierRange`:
+        // the two take the same `number | { min, max }`, and widening
+        // first would publish a band of one as `minValue: 2,
+        // maxValue: 2` — a range across a single size, where `value:
+        // 2` is the same claim said plainly.
+        eligibleQuantity:
+            band === undefined
+                ? undefined
+                : { ...quantitativeValue(band.quantity), unitText: unit },
+        seller: reference(item.seller),
     };
 }
 

package/src/jsonld/service.ts

@@ -1,7 +1,7 @@
 import type { HttpsUrl } from "../url.ts";
 import type { BusinessId, OrganizationId } from "./ids.ts";
 import { serviceId } from "./ids.ts";
-import type { JsonLdNode } from "./node.ts";
+import { type JsonLdNode, listed, reference } from "./node.ts";
 
 /**
  * What a business *does*, for the sites that sell work rather than tickets.
@@ -82,29 +82,23 @@ export interface ServiceInput {
 }
 
 /** An `Audience` node, or nothing. See `ServiceInput.audience`. */
-function audienceFor(audienceType: string | undefined): {
-    readonly audience?: JsonLdNode;
-} {
+function audienceFor(audienceType: string | undefined): JsonLdNode | undefined {
     return audienceType === undefined
-        ? {}
-        : { audience: { "@type": "Audience", audienceType } };
+        ? undefined
+        : { "@type": "Audience", audienceType };
 }
 
 /** `areaServed`, as `Place` nodes. See `ServiceArea`. */
-function areasFor(areas: readonly ServiceArea[] | undefined): {
-    readonly areaServed?: readonly JsonLdNode[];
-} {
+function areasFor(
+    areas: readonly ServiceArea[] | undefined
+): readonly JsonLdNode[] | undefined {
     // Length rather than presence: a service that serves nowhere in particular
     // says nothing, and an empty list is a claim to have been asked and had no
     // answer.
-    if (areas === undefined || areas.length === 0) return {};
-
-    return {
-        areaServed: areas.map((area) => ({
-            "@type": area.kind ?? "AdministrativeArea",
-            name: area.name,
-        })),
-    };
+    return listed(areas)?.map((area) => ({
+        "@type": area.kind ?? "AdministrativeArea",
+        name: area.name,
+    }));
 }
 
 /**
@@ -118,17 +112,11 @@ export function service(input: ServiceInput): JsonLdNode {
         "@id": serviceId(input.url),
         name: input.name,
         url: input.url,
-        ...(input.description === undefined
-            ? {}
-            : { description: input.description }),
-        ...(input.serviceType === undefined
-            ? {}
-            : { serviceType: input.serviceType }),
-        ...(input.provider === undefined
-            ? {}
-            : { provider: { "@id": input.provider } }),
-        ...audienceFor(input.audience),
-        ...areasFor(input.areaServed),
+        description: input.description,
+        serviceType: input.serviceType,
+        provider: reference(input.provider),
+        audience: audienceFor(input.audience),
+        areaServed: areasFor(input.areaServed),
     };
 }
 
@@ -212,9 +200,7 @@ export function offerCatalog(input: OfferCatalogInput): JsonLdNode {
     return {
         "@type": "OfferCatalog",
         name: input.name,
-        ...(input.description === undefined
-            ? {}
-            : { description: input.description }),
+        description: input.description,
         // Unconditional: this is the node's only link to anything.
         provider: { "@id": input.provider },
         itemListElement: input.entries.map((entry) => ({
@@ -224,13 +210,11 @@ export function offerCatalog(input: OfferCatalogInput): JsonLdNode {
                 // The id only where there is a page to hang it on. A fragment
                 // invented for an entry with no page would be an identity for
                 // something nothing else can ever refer to.
-                ...(entry.url === undefined
-                    ? {}
-                    : { "@id": serviceId(entry.url), url: entry.url }),
+                "@id":
+                    entry.url === undefined ? undefined : serviceId(entry.url),
+                url: entry.url,
                 name: entry.name,
-                ...(entry.description === undefined
-                    ? {}
-                    : { description: entry.description }),
+                description: entry.description,
             },
         })),
     };

package/src/jsonld/video.ts

@@ -227,13 +227,9 @@ export function videoObject(video: VideoInput): JsonLdNode {
             )
         ),
         uploadDate: video.uploadDate,
-        ...(video.description === undefined
-            ? {}
-            : { description: video.description }),
-        ...(duration === undefined ? {} : { duration }),
-        ...(video.contentUrl === undefined
-            ? {}
-            : { contentUrl: video.contentUrl }),
-        ...(video.embedUrl === undefined ? {} : { embedUrl: video.embedUrl }),
+        description: video.description,
+        duration,
+        contentUrl: video.contentUrl,
+        embedUrl: video.embedUrl,
     };
 }

package/src/jsonld/website.ts

@@ -1,6 +1,6 @@
 import type { HttpsUrl } from "../url.ts";
 import { type OrganizationId, websiteId } from "./ids.ts";
-import { alternateName, type JsonLdNode } from "./node.ts";
+import { alternateName, type JsonLdNode, reference } from "./node.ts";
 
 export interface WebsiteInput {
     /**
@@ -50,9 +50,7 @@ export function website(site: WebsiteInput): JsonLdNode {
         "@id": websiteId(site.url),
         name: site.name,
         url: site.url,
-        ...alternateName(site.name, site.alternateName),
-        ...(site.publisher === undefined
-            ? {}
-            : { publisher: { "@id": site.publisher } }),
+        alternateName: alternateName(site.name, site.alternateName),
+        publisher: reference(site.publisher),
     };
 }

package/src/meta/content.ts

@@ -9,32 +9,9 @@ import type { RobotsPolicy } from "./robots.ts";
 import type { ShareImage } from "./share-image.ts";
 
 /**
- * What only a consumer can supply: a page's words, and what kind of thing it is.
+ * What only a consumer can supply: a page's words, and whether it is an article.
  */
 
-/**
- * What kind of thing a page represents, for `og:type`.
- *
- * The whole vocabulary Open Graph defines, and a union for the reason
- * `RobotsDirective` is one: it is small and closed, and a value outside it is
- * not an error anywhere — a scraper that does not recognise `og:type` falls
- * back to `website` and renders a perfectly ordinary card. So `"artcile"` costs
- * you the article treatment and looks exactly like success.
- *
- * `website` is the default and the right answer for most pages. `article` is
- * the one that earns anything extra: it is what tells a scraper this is a dated
- * piece of writing rather than a section of the site.
- *
- * Reference: <https://ogp.me/#types>
- */
-export type OpenGraphType =
-    | "website"
-    | "article"
-    | "book"
-    | "profile"
-    | `music.${"song" | "album" | "playlist" | "radio_station"}`
-    | `video.${"movie" | "episode" | "tv_show" | "other"}`;
-
 /**
  * A page that is a dated piece of writing, said once.
  *
@@ -48,10 +25,11 @@ export type OpenGraphType =
  * Supplying this is what emits the `Article` node, `og:type: article` and the
  * `article:*` properties together. They are three statements of one fact, and a
  * page that could make them separately is a page that could make two of them.
- * That is why `MetaContent.type` cannot be set to `"article"`: saying a page is
- * an article without saying when it was published is the half-statement this
- * exists to prevent, and it is also the half that carries no benefit — the date
- * is the whole reason the type is worth claiming.
+ * That is why there is no `type` to set: saying a page is an article without
+ * saying when it was published is the half-statement this exists to prevent.
+ * Open Graph's other kinds (`book`, `profile`, `video.*`) each come with fields
+ * of their own; one would be added the same way, as a field that is the
+ * description, with the two made exclusive then.
  */
 export interface ArticleContent {
     /**
@@ -99,34 +77,8 @@ export interface ArticleContent {
     readonly images?: readonly ImageAsset[];
 }
 
-/**
- * What kind of page this is: an ordinary one, or an article.
- *
- * A union rather than two optional fields, so the pair cannot both be set. They
- * answer the same question — `article` decides `og:type` — and a page that
- * supplied both would have one of them silently ignored, which is the shape of
- * mistake this folder keeps removing rather than reporting.
- *
- * Both branches allow the fields to be absent, so an ordinary page writes
- * neither and gets `website`.
- */
-export type PageKind =
-    | {
-          readonly type?: Exclude<OpenGraphType, "article">;
-          readonly article?: never;
-      }
-    | {
-          readonly type?: never;
-          /**
-           * This page's publication details, if it is a dated piece of writing.
-           *
-           * One field, three outputs — see `ArticleContent`.
-           */
-          readonly article: ArticleContent;
-      };
-
-/** The fields every page has, whatever kind it is. */
-export interface MetaContentBase {
+/** What a page passes to `metaFor`: its words, its picture, and whether it is an article. */
+export interface MetaContent {
     readonly title: string;
     /**
      * Required: a page without a description leaves search engines and every
@@ -172,18 +124,14 @@ export interface MetaContentBase {
      * and never sees the page they end up on.
      */
     readonly jsonLd?: readonly JsonLdNode[];
+    /**
+     * This page's publication details, if it is a dated piece of writing:
+     * `og:type` becomes `article`, with its `article:*` properties and an
+     * `Article` node. Without it a page is a `website`. See `ArticleContent`.
+     */
+    readonly article?: ArticleContent;
 }
 
-/**
- * What a page passes to `metaFor`: its words, its picture, and what kind of
- * thing it is.
- *
- * An intersection rather than one interface because `PageKind` is a union, and
- * that union is the whole point — see it for why `type` and `article` cannot
- * both be written.
- */
-export type MetaContent = MetaContentBase & PageKind;
-
 /** Browser-UI tint. A single colour, or one per `prefers-color-scheme`. */
 export type ThemeColor =
     | string