@entifix/core 0.8.0 → 0.10.0

package/dist/rsql/facet-query-url.d.ts

@@ -0,0 +1,25 @@
+import type { Entity, EntityConstructor } from '../types/Entity.js';
+import type { EntityFacetQuery } from '../types/EntityFacets.js';
+/** The parameter naming one member to count, repeated once per facet. */
+export declare const FACET_PARAM = "facet";
+/** The parameter holding one facet's own filtering: `rsql.<member>`. */
+export declare const facetFilterParam: (member: string) => string;
+/**
+ * Serializes facet queries into query parameters: each member as a `facet`,
+ * and each one's filtering as RSQL under `rsql.<member>` — omitted when it
+ * filters nothing, so an unfiltered count keeps a clean URL.
+ */
+export declare function serializeFacetQueryParams<TEntity extends Entity>(queries: readonly EntityFacetQuery<TEntity>[]): URLSearchParams;
+/**
+ * Parses query parameters into facet queries, validated against the entity's
+ * own metadata — the server-side half of the facet protocol, and the same
+ * allowlist a load uses.
+ *
+ * A counted member must be `filterable`: a count is a question about the
+ * values a filter would choose between, and counting a member nobody may
+ * filter on would read out values the entity chose not to expose. A
+ * `localized` member is refused, since its value is a record of texts, not one
+ * to count. Every failure is an {@link EntifixBuildError}, so a `400`.
+ */
+export declare function parseFacetQueryParams<TEntity extends Entity>(entityConstructor: EntityConstructor<TEntity>, params: URLSearchParams): EntityFacetQuery<TEntity>[];
+//# sourceMappingURL=facet-query-url.d.ts.map

package/dist/rsql/facet-query-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facet-query-url.d.ts","sourceRoot":"","sources":["../../src/rsql/facet-query-url.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAUjE,yEAAyE;AACzE,eAAO,MAAM,WAAW,UAAU,CAAC;AAEnC,wEAAwE;AACxE,eAAO,MAAM,gBAAgB,GAAI,QAAQ,MAAM,KAAG,MACvB,CAAC;AAE5B;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,SAAS,MAAM,EAC9D,OAAO,EAAE,SAAS,gBAAgB,CAAC,OAAO,CAAC,EAAE,GAC5C,eAAe,CAQjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,SAAS,MAAM,EAC1D,iBAAiB,EAAE,iBAAiB,CAAC,OAAO,CAAC,EAC7C,MAAM,EAAE,eAAe,GACtB,gBAAgB,CAAC,OAAO,CAAC,EAAE,CA6C7B"}

package/dist/rsql/facet-query-url.js

@@ -0,0 +1,63 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { EntifixBuildError } from '../base-entities/entifix-error/index.js';
+import { allowedDescriptors, coerceFiltering, resolveAllowedProperty } from './coerce-rsql.js';
+import { RSQL_PARAM } from './load-request-url.js';
+import { parseRsql } from './parse-rsql.js';
+import { serializeRsql } from './serialize-rsql.js';
+/** The parameter naming one member to count, repeated once per facet. */ export const FACET_PARAM = 'facet';
+/** The parameter holding one facet's own filtering: `rsql.<member>`. */ export const facetFilterParam = (member)=>`${RSQL_PARAM}.${member}`;
+/**
+ * Serializes facet queries into query parameters: each member as a `facet`,
+ * and each one's filtering as RSQL under `rsql.<member>` — omitted when it
+ * filters nothing, so an unfiltered count keeps a clean URL.
+ */ export function serializeFacetQueryParams(queries) {
+    const params = new URLSearchParams();
+    for (const { member, filtering } of queries){
+        params.append(FACET_PARAM, member);
+        const rsql = serializeRsql(filtering);
+        if (rsql !== '') params.set(facetFilterParam(member), rsql);
+    }
+    return params;
+}
+/**
+ * Parses query parameters into facet queries, validated against the entity's
+ * own metadata — the server-side half of the facet protocol, and the same
+ * allowlist a load uses.
+ *
+ * A counted member must be `filterable`: a count is a question about the
+ * values a filter would choose between, and counting a member nobody may
+ * filter on would read out values the entity chose not to expose. A
+ * `localized` member is refused, since its value is a record of texts, not one
+ * to count. Every failure is an {@link EntifixBuildError}, so a `400`.
+ */ export function parseFacetQueryParams(entityConstructor, params) {
+    const members = params.getAll(FACET_PARAM);
+    if (members.length === 0) {
+        throw new EntifixBuildError(`name at least one "${FACET_PARAM}"`);
+    }
+    if (new Set(members).size !== members.length) {
+        throw new EntifixBuildError(`a "${FACET_PARAM}" is named twice`, undefined, {
+            members
+        });
+    }
+    const allowed = allowedDescriptors(entityConstructor, (descriptor)=>descriptor.filterable);
+    return members.map((member)=>{
+        const { key, locale } = resolveAllowedProperty(allowed, member, 'filterable');
+        if (locale !== undefined) {
+            // One locale of a localized member is prose, one value per record —
+            // there is nothing to choose between, so nothing to count.
+            throw new EntifixBuildError(`"${member}" cannot be counted`, undefined, {
+                member
+            });
+        }
+        const expression = params.get(facetFilterParam(member));
+        return _extends({
+            member: key
+        }, (expression == null ? void 0 : expression.trim()) ? {
+            filtering: [
+                coerceFiltering(entityConstructor, parseRsql(expression))
+            ]
+        } : {});
+    });
+}
+
+//# sourceMappingURL=facet-query-url.js.map

package/dist/rsql/facet-query-url.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/rsql/facet-query-url.ts"],"sourcesContent":["import { EntifixBuildError } from '../base-entities/entifix-error/index.js';\nimport type { Entity, EntityConstructor } from '../types/Entity.js';\nimport type { EntityFacetQuery } from '../types/EntityFacets.js';\nimport {\n  allowedDescriptors,\n  coerceFiltering,\n  resolveAllowedProperty,\n} from './coerce-rsql.js';\nimport { RSQL_PARAM } from './load-request-url.js';\nimport { parseRsql } from './parse-rsql.js';\nimport { serializeRsql } from './serialize-rsql.js';\n\n/** The parameter naming one member to count, repeated once per facet. */\nexport const FACET_PARAM = 'facet';\n\n/** The parameter holding one facet's own filtering: `rsql.<member>`. */\nexport const facetFilterParam = (member: string): string =>\n  `${RSQL_PARAM}.${member}`;\n\n/**\n * Serializes facet queries into query parameters: each member as a `facet`,\n * and each one's filtering as RSQL under `rsql.<member>` — omitted when it\n * filters nothing, so an unfiltered count keeps a clean URL.\n */\nexport function serializeFacetQueryParams<TEntity extends Entity>(\n  queries: readonly EntityFacetQuery<TEntity>[],\n): URLSearchParams {\n  const params = new URLSearchParams();\n  for (const { member, filtering } of queries) {\n    params.append(FACET_PARAM, member);\n    const rsql = serializeRsql(filtering);\n    if (rsql !== '') params.set(facetFilterParam(member), rsql);\n  }\n  return params;\n}\n\n/**\n * Parses query parameters into facet queries, validated against the entity's\n * own metadata — the server-side half of the facet protocol, and the same\n * allowlist a load uses.\n *\n * A counted member must be `filterable`: a count is a question about the\n * values a filter would choose between, and counting a member nobody may\n * filter on would read out values the entity chose not to expose. A\n * `localized` member is refused, since its value is a record of texts, not one\n * to count. Every failure is an {@link EntifixBuildError}, so a `400`.\n */\nexport function parseFacetQueryParams<TEntity extends Entity>(\n  entityConstructor: EntityConstructor<TEntity>,\n  params: URLSearchParams,\n): EntityFacetQuery<TEntity>[] {\n  const members = params.getAll(FACET_PARAM);\n  if (members.length === 0) {\n    throw new EntifixBuildError(`name at least one \"${FACET_PARAM}\"`);\n  }\n  if (new Set(members).size !== members.length) {\n    throw new EntifixBuildError(\n      `a \"${FACET_PARAM}\" is named twice`,\n      undefined,\n      {\n        members,\n      },\n    );\n  }\n\n  const allowed = allowedDescriptors(\n    entityConstructor,\n    descriptor => descriptor.filterable,\n  );\n\n  return members.map(member => {\n    const { key, locale } = resolveAllowedProperty(\n      allowed,\n      member,\n      'filterable',\n    );\n    if (locale !== undefined) {\n      // One locale of a localized member is prose, one value per record —\n      // there is nothing to choose between, so nothing to count.\n      throw new EntifixBuildError(`\"${member}\" cannot be counted`, undefined, {\n        member,\n      });\n    }\n    const expression = params.get(facetFilterParam(member));\n    return {\n      member: key as keyof TEntity & string,\n      ...(expression?.trim()\n        ? {\n            filtering: [\n              coerceFiltering(entityConstructor, parseRsql(expression)),\n            ],\n          }\n        : {}),\n    };\n  });\n}\n"],"names":["EntifixBuildError","allowedDescriptors","coerceFiltering","resolveAllowedProperty","RSQL_PARAM","parseRsql","serializeRsql","FACET_PARAM","facetFilterParam","member","serializeFacetQueryParams","queries","params","URLSearchParams","filtering","append","rsql","set","parseFacetQueryParams","entityConstructor","members","getAll","length","Set","size","undefined","allowed","descriptor","filterable","map","key","locale","expression","get","trim"],"mappings":";AAAA,SAASA,iBAAiB,QAAQ,0CAA0C;AAG5E,SACEC,kBAAkB,EAClBC,eAAe,EACfC,sBAAsB,QACjB,mBAAmB;AAC1B,SAASC,UAAU,QAAQ,wBAAwB;AACnD,SAASC,SAAS,QAAQ,kBAAkB;AAC5C,SAASC,aAAa,QAAQ,sBAAsB;AAEpD,uEAAuE,GACvE,OAAO,MAAMC,cAAc,QAAQ;AAEnC,sEAAsE,GACtE,OAAO,MAAMC,mBAAmB,CAACC,SAC/B,GAAGL,WAAW,CAAC,EAAEK,QAAQ,CAAC;AAE5B;;;;CAIC,GACD,OAAO,SAASC,0BACdC,OAA6C;IAE7C,MAAMC,SAAS,IAAIC;IACnB,KAAK,MAAM,EAAEJ,MAAM,EAAEK,SAAS,EAAE,IAAIH,QAAS;QAC3CC,OAAOG,MAAM,CAACR,aAAaE;QAC3B,MAAMO,OAAOV,cAAcQ;QAC3B,IAAIE,SAAS,IAAIJ,OAAOK,GAAG,CAACT,iBAAiBC,SAASO;IACxD;IACA,OAAOJ;AACT;AAEA;;;;;;;;;;CAUC,GACD,OAAO,SAASM,sBACdC,iBAA6C,EAC7CP,MAAuB;IAEvB,MAAMQ,UAAUR,OAAOS,MAAM,CAACd;IAC9B,IAAIa,QAAQE,MAAM,KAAK,GAAG;QACxB,MAAM,IAAItB,kBAAkB,CAAC,mBAAmB,EAAEO,YAAY,CAAC,CAAC;IAClE;IACA,IAAI,IAAIgB,IAAIH,SAASI,IAAI,KAAKJ,QAAQE,MAAM,EAAE;QAC5C,MAAM,IAAItB,kBACR,CAAC,GAAG,EAAEO,YAAY,gBAAgB,CAAC,EACnCkB,WACA;YACEL;QACF;IAEJ;IAEA,MAAMM,UAAUzB,mBACdkB,mBACAQ,CAAAA,aAAcA,WAAWC,UAAU;IAGrC,OAAOR,QAAQS,GAAG,CAACpB,CAAAA;QACjB,MAAM,EAAEqB,GAAG,EAAEC,MAAM,EAAE,GAAG5B,uBACtBuB,SACAjB,QACA;QAEF,IAAIsB,WAAWN,WAAW;YACxB,oEAAoE;YACpE,2DAA2D;YAC3D,MAAM,IAAIzB,kBAAkB,CAAC,CAAC,EAAES,OAAO,mBAAmB,CAAC,EAAEgB,WAAW;gBACtEhB;YACF;QACF;QACA,MAAMuB,aAAapB,OAAOqB,GAAG,CAACzB,iBAAiBC;QAC/C,OAAO;YACLA,QAAQqB;WACJE,CAAAA,8BAAAA,WAAYE,IAAI,MAChB;YACEpB,WAAW;gBACTZ,gBAAgBiB,mBAAmBd,UAAU2B;aAC9C;QACH,IACA,CAAC;IAET;AACF"}

package/dist/rsql/index.d.ts

@@ -1,4 +1,5 @@
 export * from './coerce-rsql.js';
+export * from './facet-query-url.js';
 export * from './load-request-url.js';
 export * from './parse-rsql.js';
 export * from './rsql-operators.js';

package/dist/rsql/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/rsql/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/rsql/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC"}

package/dist/rsql/index.js

@@ -1,4 +1,5 @@
 export * from './coerce-rsql.js';
+export * from './facet-query-url.js';
 export * from './load-request-url.js';
 export * from './parse-rsql.js';
 export * from './rsql-operators.js';

package/dist/rsql/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/rsql/index.ts"],"sourcesContent":["export * from './coerce-rsql.js';\nexport * from './load-request-url.js';\nexport * from './parse-rsql.js';\nexport * from './rsql-operators.js';\nexport * from './rsql-values.js';\nexport * from './serialize-rsql.js';\nexport * from './sort-param.js';\n"],"names":[],"mappings":"AAAA,cAAc,mBAAmB;AACjC,cAAc,wBAAwB;AACtC,cAAc,kBAAkB;AAChC,cAAc,sBAAsB;AACpC,cAAc,mBAAmB;AACjC,cAAc,sBAAsB;AACpC,cAAc,kBAAkB"}
+{"version":3,"sources":["../../src/rsql/index.ts"],"sourcesContent":["export * from './coerce-rsql.js';\nexport * from './facet-query-url.js';\nexport * from './load-request-url.js';\nexport * from './parse-rsql.js';\nexport * from './rsql-operators.js';\nexport * from './rsql-values.js';\nexport * from './serialize-rsql.js';\nexport * from './sort-param.js';\n"],"names":[],"mappings":"AAAA,cAAc,mBAAmB;AACjC,cAAc,uBAAuB;AACrC,cAAc,wBAAwB;AACtC,cAAc,kBAAkB;AAChC,cAAc,sBAAsB;AACpC,cAAc,mBAAmB;AACjC,cAAc,sBAAsB;AACpC,cAAc,kBAAkB"}

package/dist/types/EntityFacets.d.ts

@@ -0,0 +1,30 @@
+import type { Entity } from './Entity.js';
+import type { EntityFiltering } from './EntityFiltering.js';
+/**
+ * One member to count the values of, under its own filtering.
+ *
+ * Each facet carries its own filtering rather than sharing one, because the
+ * counts a shop shows are usually **disjunctive**: a brand facet is counted
+ * under every filter except the brand choice itself, so choosing one brand
+ * does not drop every other brand to zero. Which filters a facet leaves out is
+ * the caller's to say — the counter counts what it is asked to.
+ */
+export interface EntityFacetQuery<TEntity extends Entity = Entity> {
+    readonly member: keyof TEntity & string;
+    readonly filtering?: EntityFiltering<TEntity>[];
+}
+/** One value a member holds, and how many records hold it. */
+export interface EntityFacetValue {
+    readonly value: string | number | boolean;
+    readonly count: number;
+}
+/**
+ * The values each queried member holds, keyed by the member as it was asked
+ * for. Every queried member is present; one no record holds is an empty list.
+ * A value held by no record is absent rather than counted `0`, since the
+ * counter cannot know which values the caller offers.
+ *
+ * Ordered by count, highest first, then by value.
+ */
+export type EntityFacetCounts = Readonly<Record<string, readonly EntityFacetValue[]>>;
+//# sourceMappingURL=EntityFacets.d.ts.map

package/dist/types/EntityFacets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntityFacets.d.ts","sourceRoot":"","sources":["../../src/types/EntityFacets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM;IAC/D,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,GAAG,MAAM,CAAC;IACxC,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,CAAC,OAAO,CAAC,EAAE,CAAC;CACjD;AAED,8DAA8D;AAC9D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CACtC,MAAM,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAC,CAC5C,CAAC"}

package/dist/types/EntityFacets.js

@@ -0,0 +1,10 @@
+/**
+ * The values each queried member holds, keyed by the member as it was asked
+ * for. Every queried member is present; one no record holds is an empty list.
+ * A value held by no record is absent rather than counted `0`, since the
+ * counter cannot know which values the caller offers.
+ *
+ * Ordered by count, highest first, then by value.
+ */ export { };
+
+//# sourceMappingURL=EntityFacets.js.map

package/dist/types/EntityFacets.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/EntityFacets.ts"],"sourcesContent":["import type { Entity } from './Entity.js';\nimport type { EntityFiltering } from './EntityFiltering.js';\n\n/**\n * One member to count the values of, under its own filtering.\n *\n * Each facet carries its own filtering rather than sharing one, because the\n * counts a shop shows are usually **disjunctive**: a brand facet is counted\n * under every filter except the brand choice itself, so choosing one brand\n * does not drop every other brand to zero. Which filters a facet leaves out is\n * the caller's to say — the counter counts what it is asked to.\n */\nexport interface EntityFacetQuery<TEntity extends Entity = Entity> {\n  readonly member: keyof TEntity & string;\n  readonly filtering?: EntityFiltering<TEntity>[];\n}\n\n/** One value a member holds, and how many records hold it. */\nexport interface EntityFacetValue {\n  readonly value: string | number | boolean;\n  readonly count: number;\n}\n\n/**\n * The values each queried member holds, keyed by the member as it was asked\n * for. Every queried member is present; one no record holds is an empty list.\n * A value held by no record is absent rather than counted `0`, since the\n * counter cannot know which values the caller offers.\n *\n * Ordered by count, highest first, then by value.\n */\nexport type EntityFacetCounts = Readonly<\n  Record<string, readonly EntityFacetValue[]>\n>;\n"],"names":[],"mappings":"AAuBA;;;;;;;CAOC,GACD,WAEE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@entifix/core",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "The entity system: decorators that make a class describe itself, entity serialization, the RSQL query protocol and the wire envelopes.",
   "license": "MIT",
   "repository": {
@@ -53,9 +53,9 @@
     "@swc/helpers": "0.5.23"
   },
   "peerDependencies": {
-    "effect": "^4.0.5"
+    "effect": "^4.0.6"
   },
   "devDependencies": {
-    "effect": "4.0.5"
+    "effect": "4.0.6"
   }
 }