@rebasepro/common 0.23.0 → 0.24.1-canary.g19596ef

package/dist/collections/unknown-field.es.js

@@ -0,0 +1,135 @@
+import { fieldKeyForColumn, findRelation, resolveCollectionRelations } from "../util/relations.es.js";
+import { apiHiddenFieldNames } from "./field-access.es.js";
+//#region src/collections/unknown-field.ts
+/**
+* The fields an unknown-field answer offers as valid, sorted: what a query on
+* this collection can name as a column. A relation contributes its foreign key
+* (`authorId`) when the key is on this table, and nothing otherwise. An
+* `excludeFromApi` field is never offered.
+*
+* Read off the collection rather than the table, so the REST check — which
+* holds no table — lists exactly what the driver lists.
+*/
+function queryableFieldNames(collection) {
+	const hidden = apiHiddenFieldNames(collection);
+	const names = /* @__PURE__ */ new Set();
+	let relations;
+	for (const [key, property] of Object.entries(collection.properties ?? {})) {
+		if (property?.type === "relation") {
+			relations ??= resolveCollectionRelations(collection);
+			const relation = findRelation(relations, key);
+			if (relation?.kind === "belongsTo") names.add(fieldKeyForColumn(collection, relation.localKey));
+			continue;
+		}
+		names.add(key);
+	}
+	return [...names].filter((name) => !hidden.has(name)).sort();
+}
+var validList = (validFields) => validFields.length > 0 ? `. Valid fields: ${validFields.join(", ")}` : "";
+/** A filter key that resolves to nothing on `collectionPath`. */
+function unknownFilterField(field, collectionPath, validFields) {
+	return {
+		message: `Unknown filter field '${field}' on collection '${collectionPath}'${validList(validFields)}`,
+		code: "UNKNOWN_FILTER_FIELD",
+		details: {
+			field,
+			collection: collectionPath,
+			...validFields.length > 0 && { validFields }
+		}
+	};
+}
+/** `author.emial` — a relation path whose last segment names nothing on the relation's target. */
+function unknownRelationTargetField(path, target, collectionPath) {
+	return {
+		message: `Unknown field '${path.fieldKey}' on '${target.slug}', the target of relation '${path.relationKey}' on collection '${collectionPath}'${validList(target.validFields)}`,
+		code: "UNKNOWN_FILTER_FIELD",
+		details: {
+			field: path.field,
+			collection: collectionPath,
+			relation: path.relationKey,
+			targetCollection: target.slug,
+			...target.validFields.length > 0 && { validFields: target.validFields }
+		}
+	};
+}
+/** An `orderBy` key that resolves to nothing. `collectionName` is absent when the read carries no collection. */
+function unknownOrderByField(orderBy, collectionName, validFields) {
+	return {
+		message: `Unknown orderBy field '${orderBy}'${collectionName ? ` on collection '${collectionName}'` : ""}${validList(validFields)}`,
+		code: "UNKNOWN_ORDER_BY_FIELD",
+		details: {
+			field: orderBy,
+			...collectionName && { collection: collectionName },
+			...validFields.length > 0 && { validFields }
+		}
+	};
+}
+/** A `fields` entry that names nothing. */
+function unknownProjectionField(name, collectionName, validFields) {
+	return {
+		message: `Unknown field '${name}' in \`fields\` on collection '${collectionName}'. Valid fields: ${validFields.join(", ")}`,
+		code: "UNKNOWN_FIELD",
+		details: {
+			field: name,
+			collection: collectionName
+		}
+	};
+}
+/**
+* An `include` naming no relation of the collection. `validRelations` is what
+* the collection declares, never an `excludeFromApi` relation.
+*/
+function unknownIncludeRelation(key, collectionName, validRelations) {
+	return {
+		message: `Unknown relation '${key}' on collection '${collectionName}'` + (validRelations.length > 0 ? `. Its relations are: ${validRelations.join(", ")}` : ". It declares no relations."),
+		code: "UNKNOWN_RELATION",
+		details: {
+			relation: key,
+			collection: collectionName,
+			...validRelations.length > 0 && { validRelations }
+		}
+	};
+}
+/** The relations an unknown-relation answer offers, sorted — never an `excludeFromApi` one. */
+function includableRelationNames(collection) {
+	const hidden = apiHiddenFieldNames(collection);
+	return Object.keys(resolveCollectionRelations(collection)).filter((key) => !hidden.has(key)).sort();
+}
+/**
+* An aggregate's `select` field or `groupBy` key that names no column.
+* `forWhat` is where it was named: `sum()`, `count()`, `groupBy`.
+* `validFields` is {@link queryableFieldNames}, never an `excludeFromApi` field.
+*/
+function unknownAggregateField(field, forWhat, validFields) {
+	return {
+		message: `Unknown field '${field}' in ${forWhat}${validList(validFields)}`,
+		code: "UNKNOWN_AGGREGATE_FIELD",
+		details: {
+			field,
+			...validFields.length > 0 && { validFields }
+		}
+	};
+}
+/**
+* The properties a `vector_search` can name, sorted: those declared
+* `{ type: "vector" }`, never an `excludeFromApi` one.
+*/
+function vectorPropertyNames(collection) {
+	const hidden = apiHiddenFieldNames(collection);
+	return Object.entries(collection.properties ?? {}).filter(([key, property]) => property?.type === "vector" && !hidden.has(key)).map(([key]) => key).sort();
+}
+/** A `vector_search` naming no vector property. `vectorProperties` is {@link vectorPropertyNames}. */
+function unknownVectorProperty(property, vectorProperties) {
+	return {
+		message: `Unknown vector property "${property}". ` + (vectorProperties.length > 0 ? `This collection's vector properties are: ${vectorProperties.join(", ")}.` : "This collection declares no `vector` property to search."),
+		code: "UNKNOWN_VECTOR_PROPERTY",
+		details: {
+			property,
+			...vectorProperties.length > 0 && { vectorProperties }
+		}
+	};
+}
+//#endregion
+export { includableRelationNames, queryableFieldNames, unknownAggregateField, unknownFilterField, unknownIncludeRelation, unknownOrderByField, unknownProjectionField, unknownRelationTargetField, unknownVectorProperty, vectorPropertyNames };
+
+//# sourceMappingURL=unknown-field.es.js.map

package/dist/collections/unknown-field.es.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unknown-field.es.js","names":[],"sources":["../../src/collections/unknown-field.ts"],"sourcesContent":["import type { CollectionConfig, Property } from \"@rebasepro/types\";\nimport { fieldKeyForColumn, findRelation, resolveCollectionRelations } from \"../util/relations\";\nimport { apiHiddenFieldNames } from \"./field-access\";\n\n/**\n * The answers a query gets for naming a field that does not exist — written\n * once, here, because two layers give them.\n *\n * The driver gives them for a typo. The REST check gives the same ones for a\n * field marked `excludeFromApi`: OpenAPI, `list_collections` and the generated\n * SDK all leave such a field out, so anything but the typo's answer — \"not\n * readable\", a different message, a list that names it — confirms it exists.\n * Both build the answer from these functions, so the two cannot drift apart by\n * a byte. Each returns the parts of the 400 (`message`, `code`, `details`) and\n * the caller wraps them in its own error type.\n *\n * @module\n */\n\nexport interface UnknownFieldAnswer {\n    message: string;\n    code: string;\n    details: Record<string, unknown>;\n}\n\n/**\n * The fields an unknown-field answer offers as valid, sorted: what a query on\n * this collection can name as a column. A relation contributes its foreign key\n * (`authorId`) when the key is on this table, and nothing otherwise. An\n * `excludeFromApi` field is never offered.\n *\n * Read off the collection rather than the table, so the REST check — which\n * holds no table — lists exactly what the driver lists.\n */\nexport function queryableFieldNames(collection: CollectionConfig): string[] {\n    const hidden = apiHiddenFieldNames(collection);\n    const names = new Set<string>();\n    let relations: ReturnType<typeof resolveCollectionRelations> | undefined;\n    for (const [key, property] of Object.entries(collection.properties ?? {})) {\n        if ((property as Property | undefined)?.type === \"relation\") {\n            relations ??= resolveCollectionRelations(collection);\n            const relation = findRelation(relations, key);\n            if (relation?.kind === \"belongsTo\") names.add(fieldKeyForColumn(collection, relation.localKey));\n            continue;\n        }\n        names.add(key);\n    }\n    return [...names].filter(name => !hidden.has(name)).sort();\n}\n\nconst validList = (validFields: string[]): string =>\n    validFields.length > 0 ? `. Valid fields: ${validFields.join(\", \")}` : \"\";\n\n/** A filter key that resolves to nothing on `collectionPath`. */\nexport function unknownFilterField(field: string, collectionPath: string, validFields: string[]): UnknownFieldAnswer {\n    return {\n        message: `Unknown filter field '${field}' on collection '${collectionPath}'${validList(validFields)}`,\n        code: \"UNKNOWN_FILTER_FIELD\",\n        details: { field, collection: collectionPath, ...(validFields.length > 0 && { validFields }) }\n    };\n}\n\n/** `author.emial` — a relation path whose last segment names nothing on the relation's target. */\nexport function unknownRelationTargetField(\n    path: { field: string; relationKey: string; fieldKey: string },\n    target: { slug: string; validFields: string[] },\n    collectionPath: string\n): UnknownFieldAnswer {\n    return {\n        message: `Unknown field '${path.fieldKey}' on '${target.slug}', the target of relation ` +\n            `'${path.relationKey}' on collection '${collectionPath}'${validList(target.validFields)}`,\n        code: \"UNKNOWN_FILTER_FIELD\",\n        details: {\n            field: path.field,\n            collection: collectionPath,\n            relation: path.relationKey,\n            targetCollection: target.slug,\n            ...(target.validFields.length > 0 && { validFields: target.validFields })\n        }\n    };\n}\n\n/** An `orderBy` key that resolves to nothing. `collectionName` is absent when the read carries no collection. */\nexport function unknownOrderByField(orderBy: string, collectionName: string | undefined, validFields: string[]): UnknownFieldAnswer {\n    const onCollection = collectionName ? ` on collection '${collectionName}'` : \"\";\n    return {\n        message: `Unknown orderBy field '${orderBy}'${onCollection}${validList(validFields)}`,\n        code: \"UNKNOWN_ORDER_BY_FIELD\",\n        details: {\n            field: orderBy,\n            ...(collectionName && { collection: collectionName }),\n            ...(validFields.length > 0 && { validFields })\n        }\n    };\n}\n\n/** A `fields` entry that names nothing. */\nexport function unknownProjectionField(name: string, collectionName: string, validFields: string[]): UnknownFieldAnswer {\n    return {\n        message: `Unknown field '${name}' in \\`fields\\` on collection '${collectionName}'. Valid fields: ${validFields.join(\", \")}`,\n        code: \"UNKNOWN_FIELD\",\n        details: { field: name, collection: collectionName }\n    };\n}\n\n/**\n * An `include` naming no relation of the collection. `validRelations` is what\n * the collection declares, never an `excludeFromApi` relation.\n */\nexport function unknownIncludeRelation(key: string, collectionName: string, validRelations: string[]): UnknownFieldAnswer {\n    return {\n        message: `Unknown relation '${key}' on collection '${collectionName}'`\n            + (validRelations.length > 0\n                ? `. Its relations are: ${validRelations.join(\", \")}`\n                : \". It declares no relations.\"),\n        code: \"UNKNOWN_RELATION\",\n        details: { relation: key, collection: collectionName, ...(validRelations.length > 0 && { validRelations }) }\n    };\n}\n\n/** The relations an unknown-relation answer offers, sorted — never an `excludeFromApi` one. */\nexport function includableRelationNames(collection: CollectionConfig): string[] {\n    const hidden = apiHiddenFieldNames(collection);\n    return Object.keys(resolveCollectionRelations(collection)).filter(key => !hidden.has(key)).sort();\n}\n\n/**\n * An aggregate's `select` field or `groupBy` key that names no column.\n * `forWhat` is where it was named: `sum()`, `count()`, `groupBy`.\n * `validFields` is {@link queryableFieldNames}, never an `excludeFromApi` field.\n */\nexport function unknownAggregateField(field: string, forWhat: string, validFields: string[]): UnknownFieldAnswer {\n    return {\n        message: `Unknown field '${field}' in ${forWhat}${validList(validFields)}`,\n        code: \"UNKNOWN_AGGREGATE_FIELD\",\n        details: { field, ...(validFields.length > 0 && { validFields }) }\n    };\n}\n\n/**\n * The properties a `vector_search` can name, sorted: those declared\n * `{ type: \"vector\" }`, never an `excludeFromApi` one.\n */\nexport function vectorPropertyNames(collection: CollectionConfig): string[] {\n    const hidden = apiHiddenFieldNames(collection);\n    return Object.entries(collection.properties ?? {})\n        .filter(([key, property]) => (property as Property | undefined)?.type === \"vector\" && !hidden.has(key))\n        .map(([key]) => key)\n        .sort();\n}\n\n/** A `vector_search` naming no vector property. `vectorProperties` is {@link vectorPropertyNames}. */\nexport function unknownVectorProperty(property: string, vectorProperties: string[]): UnknownFieldAnswer {\n    return {\n        message: `Unknown vector property \"${property}\". ` +\n            (vectorProperties.length > 0\n                ? `This collection's vector properties are: ${vectorProperties.join(\", \")}.`\n                : \"This collection declares no `vector` property to search.\"),\n        code: \"UNKNOWN_VECTOR_PROPERTY\",\n        details: { property, ...(vectorProperties.length > 0 && { vectorProperties }) }\n    };\n}\n"],"mappings":"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"}

package/dist/data/buildRebaseData.d.ts

@@ -22,6 +22,28 @@ export interface EntityDataOptions {
         relations?: unknown[];
         slug?: string;
     } | undefined;
+    /**
+     * Translate the path a collection is addressed by into the path its driver
+     * stores it under.
+     *
+     * The admin addresses every collection by its slug, and a Firestore or
+     * MongoDB collection may declare a `path` of its own: `fs_diagnosis` stored
+     * at `diagnosis`, and `fs_diagnosis/abc/locales` at `diagnosis/abc/locales`.
+     * Only the driver is handed the stored path. Rows keep the address they
+     * were asked for by, because that is what the admin resolves their
+     * collection, routes and deletes by.
+     *
+     * Late-bound, like `resolveCollection`. Absent, or answering `undefined`,
+     * the address is the stored path.
+     */
+    resolveDataPath?: (path: string) => string | undefined;
+    /**
+     * The slug a property of the proxy names (`data.myNotes`). Absent, a
+     * property is its snake_case (`my_notes`). The server passes
+     * `createAccessorSlugResolver` over its collection registry, so a
+     * collection is reachable under the accessor its generated type has.
+     */
+    resolveAccessor?: (property: string) => string;
 }
 export declare function buildRebaseData(driver: DataDriver, options?: EntityDataOptions): RebaseData;
 /**
@@ -50,8 +72,15 @@ export declare function wrapAsEntityData(sdkData: Pick<RebaseSdkData, "collectio
  * the flat SDK data layer (`context.data`) from an existing Entity data layer
  * — e.g. the admin routes its Entity data via `useData()` and exposes the
  * same routing as flat `context.data` for callbacks by wrapping it here.
+ *
+ * `DB` is the generated `Database` the result is typed from. One object serves
+ * every `Database` — each accessor is resolved by name when it is read — so it
+ * describes the result and changes nothing it does. Only an explicit type
+ * argument sets it (`NoInfer`): inferred from where the result is assigned, it
+ * would be whatever that place declares — an untyped `Promise<RebaseSdkData>`
+ * made it `RebaseSdkData | PromiseLike<RebaseSdkData>`. Untyped by default.
  */
-export declare function wrapAsSdkData(entityData: RebaseData): RebaseSdkData;
+export declare function wrapAsSdkData<DB = unknown>(entityData: RebaseData, options?: Pick<EntityDataOptions, "resolveAccessor">): RebaseSdkData<NoInfer<DB>>;
 /**
  * Build a flat {@link RebaseSdkData} from a `DataDriver`.
  *
@@ -63,5 +92,13 @@ export declare function wrapAsSdkData(entityData: RebaseData): RebaseSdkData;
  * the admin's view-model and never reaches here.
  *
  * The admin uses {@link buildRebaseData} (Entity) over its own driver.
+ *
+ * `options.resolveAccessor` names the slug a property is (see
+ * `createAccessorSlugResolver`); absent, `data.myNotes` is `my_notes`.
+ *
+ * `DB` types the result from a generated `Database` — `buildSdkData<Database>(driver)`
+ * is the plane `context.data` is in a project that registered it. It describes
+ * the object and changes nothing it does, and only an explicit type argument
+ * sets it (see {@link wrapAsSdkData}); untyped by default.
  */
-export declare function buildSdkData(driver: DataDriver): RebaseSdkData;
+export declare function buildSdkData<DB = unknown>(driver: DataDriver, options?: Pick<EntityDataOptions, "resolveAccessor">): RebaseSdkData<NoInfer<DB>>;