@org-quicko/silo-client 1.0.0 → 1.0.1

package/dist/entries/entry-envelope.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The four keys silo puts on every entry alongside the author's own fields.
+ *
+ * `rev` is here because `replace()` and `delete()` require the revision the
+ * caller expects and a mismatch is a `409`, so the number has to survive the
+ * trip from a read to a write. The timestamps are ISO-8601 strings rather than
+ * `Date`s, and `created_at` keeps the wire's spelling, because a row read from
+ * one call and handed to the next unchanged is worth more than a prettier one.
+ *
+ * No field can collide with these: silo refuses a schema declaring one and an
+ * entry carrying one (D62).
+ */
+export interface EntryEnvelope {
+    id: string;
+    rev: number;
+    created_at: string;
+    updated_at: string;
+}

package/dist/entries/entry-read-options.d.cts

@@ -0,0 +1,16 @@
+import type { RequestOptions } from "../request-options.cjs";
+/**
+ * What every read accepts on top of the cancellation options.
+ *
+ * `variables: "raw"` answers the `{{NAME}}` templates as stored instead of
+ * what they resolve to. An editor wants exactly that: seeding a form with a
+ * resolved value and saving it back replaces the reference somebody typed with
+ * a snapshot of what it meant in one environment on one day, and a template
+ * cannot be recovered from its substitution (D57).
+ *
+ * Reads resolve by default, because an application reading content should not
+ * have to opt in to a usable value.
+ */
+export interface EntryReadOptions extends RequestOptions {
+    variables?: "raw";
+}

package/dist/entries/entry-read-options.d.ts

@@ -0,0 +1,16 @@
+import type { RequestOptions } from "../request-options.js";
+/**
+ * What every read accepts on top of the cancellation options.
+ *
+ * `variables: "raw"` answers the `{{NAME}}` templates as stored instead of
+ * what they resolve to. An editor wants exactly that: seeding a form with a
+ * resolved value and saving it back replaces the reference somebody typed with
+ * a snapshot of what it meant in one environment on one day, and a template
+ * cannot be recovered from its substitution (D57).
+ *
+ * Reads resolve by default, because an application reading content should not
+ * have to opt in to a usable value.
+ */
+export interface EntryReadOptions extends RequestOptions {
+    variables?: "raw";
+}

package/dist/entries/entry-reader.d.cts

@@ -1,26 +1,26 @@
-import type { RequestOptions } from "../request-options.cjs";
-import type { EntryContext } from "./entry-base.cjs";
+import type { ScopeReference } from "../scope/scope-reference.cjs";
+import type { Entry } from "./entry.cjs";
 import type { EntryListQuery } from "./entry-list-query.cjs";
 import { EntryPage } from "./entry-page.cjs";
 import { EntryPageStream } from "./entry-page-stream.cjs";
-import type { EntryPayload } from "./entry-payload.cjs";
+import type { EntryReadOptions } from "./entry-read-options.cjs";
 import { EntryStream } from "./entry-stream.cjs";
 /**
- * Reads entries out of one collection and hands each answer to `wrap`.
+ * The four reads of one collection: one entry, one page, every entry, every
+ * page.
  *
- * A collection holds two: one asks for substituted values and answers
- * snapshots, the other asks for the stored templates and answers editable
- * entries. Both read the same routes, so the paging is written once here.
+ * Nothing is mapped on the way through — an answer is the wire's own row
+ * (D62) — so what this class actually owns is the paging the four share and
+ * the one place `variables` is turned into a query parameter.
  */
-export declare class EntryReader<Row> {
-    private readonly context;
-    private readonly variables;
-    private readonly wrap;
-    constructor(context: EntryContext, variables: "raw" | undefined, wrap: (payload: EntryPayload) => Row);
-    get(id: string, options?: RequestOptions): Promise<Row>;
-    list(query?: EntryListQuery, options?: RequestOptions): Promise<EntryPage<Row>>;
+export declare class EntryReader<Fields> {
+    private readonly scope;
+    private readonly collection;
+    constructor(scope: ScopeReference, collection: string);
+    get(id: string, options?: EntryReadOptions): Promise<Entry<Fields>>;
+    list(query?: EntryListQuery, options?: EntryReadOptions): Promise<EntryPage<Entry<Fields>>>;
     /** Every matching entry, one at a time, `limit` rows per request. */
-    all(query?: EntryListQuery, options?: RequestOptions): EntryStream<Row>;
+    all(query?: EntryListQuery, options?: EntryReadOptions): EntryStream<Entry<Fields>>;
     /** Every matching page, one at a time. */
-    pages(query?: EntryListQuery, options?: RequestOptions): EntryPageStream<Row>;
+    pages(query?: EntryListQuery, options?: EntryReadOptions): EntryPageStream<Entry<Fields>>;
 }

package/dist/entries/entry-reader.d.ts

@@ -1,26 +1,26 @@
-import type { RequestOptions } from "../request-options.js";
-import type { EntryContext } from "./entry-base.js";
+import type { ScopeReference } from "../scope/scope-reference.js";
+import type { Entry } from "./entry.js";
 import type { EntryListQuery } from "./entry-list-query.js";
 import { EntryPage } from "./entry-page.js";
 import { EntryPageStream } from "./entry-page-stream.js";
-import type { EntryPayload } from "./entry-payload.js";
+import type { EntryReadOptions } from "./entry-read-options.js";
 import { EntryStream } from "./entry-stream.js";
 /**
- * Reads entries out of one collection and hands each answer to `wrap`.
+ * The four reads of one collection: one entry, one page, every entry, every
+ * page.
  *
- * A collection holds two: one asks for substituted values and answers
- * snapshots, the other asks for the stored templates and answers editable
- * entries. Both read the same routes, so the paging is written once here.
+ * Nothing is mapped on the way through — an answer is the wire's own row
+ * (D62) — so what this class actually owns is the paging the four share and
+ * the one place `variables` is turned into a query parameter.
  */
-export declare class EntryReader<Row> {
-    private readonly context;
-    private readonly variables;
-    private readonly wrap;
-    constructor(context: EntryContext, variables: "raw" | undefined, wrap: (payload: EntryPayload) => Row);
-    get(id: string, options?: RequestOptions): Promise<Row>;
-    list(query?: EntryListQuery, options?: RequestOptions): Promise<EntryPage<Row>>;
+export declare class EntryReader<Fields> {
+    private readonly scope;
+    private readonly collection;
+    constructor(scope: ScopeReference, collection: string);
+    get(id: string, options?: EntryReadOptions): Promise<Entry<Fields>>;
+    list(query?: EntryListQuery, options?: EntryReadOptions): Promise<EntryPage<Entry<Fields>>>;
     /** Every matching entry, one at a time, `limit` rows per request. */
-    all(query?: EntryListQuery, options?: RequestOptions): EntryStream<Row>;
+    all(query?: EntryListQuery, options?: EntryReadOptions): EntryStream<Entry<Fields>>;
     /** Every matching page, one at a time. */
-    pages(query?: EntryListQuery, options?: RequestOptions): EntryPageStream<Row>;
+    pages(query?: EntryListQuery, options?: EntryReadOptions): EntryPageStream<Entry<Fields>>;
 }

package/dist/entries/entry.d.cts

@@ -1,25 +1,13 @@
-import type { RequestOptions } from "../request-options.cjs";
-import { ResolvedEntry } from "./resolved-entry.cjs";
+import type { EntryEnvelope } from "./entry-envelope.cjs";
 /**
- * An editable entry, from a raw read: `posts.edit(id)`, a create, a
- * replace, or any read on a client constructed with `variables: "raw"`.
- * `fields` is mutable again here, undoing `ResolvedEntry`'s narrowing.
+ * One entry exactly as the API answers it: the author's fields and the
+ * envelope in one flat object, with nothing renamed, nested or wrapped.
+ *
+ * This is a plain value. It carries no transport, no scope and no methods, so
+ * it logs as its own contents, survives `structuredClone`, and drops into a
+ * store or React state as-is. Writes go through the collection —
+ * `posts.replace(id, rev, fields)`, `posts.delete(id, rev)` — where the
+ * revision being sent is visible at the call site instead of hidden inside an
+ * object (D62).
  */
-export declare class Entry<Fields> extends ResolvedEntry<Fields> {
-    rev: number;
-    createdAt: Date;
-    updatedAt: Date;
-    fields: Fields;
-    private saving;
-    /**
-     * Sends `PUT` with the rev this instance holds, adopts the rev and
-     * timestamps the response answers, and mutates in place. A second
-     * overlapping call on the same instance is refused locally — it would
-     * send a rev already known to be stale.
-     */
-    save(options?: RequestOptions): Promise<this>;
-    /** Re-reads this entry raw, and replaces `fields`, `rev` and the
-     * timestamps in place — what a `ConflictError` from `save()` calls for. */
-    refresh(options?: RequestOptions): Promise<this>;
-    private adopt;
-}
+export type Entry<Fields = Record<string, unknown>> = Fields & EntryEnvelope;

package/dist/entries/entry.d.ts

@@ -1,25 +1,13 @@
-import type { RequestOptions } from "../request-options.js";
-import { ResolvedEntry } from "./resolved-entry.js";
+import type { EntryEnvelope } from "./entry-envelope.js";
 /**
- * An editable entry, from a raw read: `posts.edit(id)`, a create, a
- * replace, or any read on a client constructed with `variables: "raw"`.
- * `fields` is mutable again here, undoing `ResolvedEntry`'s narrowing.
+ * One entry exactly as the API answers it: the author's fields and the
+ * envelope in one flat object, with nothing renamed, nested or wrapped.
+ *
+ * This is a plain value. It carries no transport, no scope and no methods, so
+ * it logs as its own contents, survives `structuredClone`, and drops into a
+ * store or React state as-is. Writes go through the collection —
+ * `posts.replace(id, rev, fields)`, `posts.delete(id, rev)` — where the
+ * revision being sent is visible at the call site instead of hidden inside an
+ * object (D62).
  */
-export declare class Entry<Fields> extends ResolvedEntry<Fields> {
-    rev: number;
-    createdAt: Date;
-    updatedAt: Date;
-    fields: Fields;
-    private saving;
-    /**
-     * Sends `PUT` with the rev this instance holds, adopts the rev and
-     * timestamps the response answers, and mutates in place. A second
-     * overlapping call on the same instance is refused locally — it would
-     * send a rev already known to be stale.
-     */
-    save(options?: RequestOptions): Promise<this>;
-    /** Re-reads this entry raw, and replaces `fields`, `rev` and the
-     * timestamps in place — what a `ConflictError` from `save()` calls for. */
-    refresh(options?: RequestOptions): Promise<this>;
-    private adopt;
-}
+export type Entry<Fields = Record<string, unknown>> = Fields & EntryEnvelope;

package/dist/index.cjs

@@ -53,8 +53,6 @@ __export(exports_src, {
   Search: () => Search,
   RowStream: () => RowStream,
   RouteInventory: () => RouteInventory,
-  ResolvedEntry: () => ResolvedEntry,
-  ReservedFieldNames: () => ReservedFieldNames,
   RequestAbortedError: () => RequestAbortedError,
   RenameReport: () => RenameReport,
   Projects: () => Projects,
@@ -90,8 +88,6 @@ __export(exports_src, {
   EntryReader: () => EntryReader,
   EntryPageStream: () => EntryPageStream,
   EntryPage: () => EntryPage,
-  EntryBase: () => EntryBase,
-  Entry: () => Entry,
   ConflictError: () => ConflictError,
   Collections: () => Collections,
   CollectionSchema: () => CollectionSchema,
@@ -779,96 +775,6 @@ class ProjectVariables {
   }
 }
 
-// src/entries/entry-mapper.ts
-class EntryMapper {
-  static fieldsOf(payload) {
-    const { id: _id, rev: _rev, created_at: _createdAt, updated_at: _updatedAt, ...fields } = payload;
-    return fields;
-  }
-  static toPayload(id, rev, fields, createdAt, updatedAt) {
-    return {
-      id,
-      rev,
-      ...fields,
-      created_at: createdAt.toISOString(),
-      updated_at: updatedAt.toISOString()
-    };
-  }
-}
-
-// src/entries/entry-base.ts
-class EntryBase {
-  context;
-  id;
-  rev;
-  createdAt;
-  updatedAt;
-  fields;
-  constructor(context, payload) {
-    this.context = context;
-    this.id = String(payload.id);
-    this.rev = Number(payload.rev);
-    this.createdAt = new Date(payload.created_at);
-    this.updatedAt = new Date(payload.updated_at);
-    this.fields = EntryMapper.fieldsOf(payload);
-  }
-  toJSON() {
-    return EntryMapper.toPayload(this.id, this.rev, this.fields, this.createdAt, this.updatedAt);
-  }
-  async delete(options = {}) {
-    await this.context.transport.empty({
-      method: "DELETE",
-      path: ApiPath.entry(this.context.project, this.context.environment, this.context.collection, this.id),
-      query: { rev: this.rev },
-      ...options
-    });
-  }
-}
-
-// src/entries/resolved-entry.ts
-class ResolvedEntry extends EntryBase {
-}
-
-// src/entries/entry.ts
-class Entry extends ResolvedEntry {
-  saving = false;
-  async save(options = {}) {
-    if (this.saving) {
-      throw new Error(`cannot save entry "${this.id}": a previous save() on this instance has not finished yet`);
-    }
-    this.saving = true;
-    try {
-      const payload = await this.context.transport.json({
-        method: "PUT",
-        path: ApiPath.entry(this.context.project, this.context.environment, this.context.collection, this.id),
-        query: { rev: this.rev, variables: "raw" },
-        body: this.fields,
-        ...options
-      });
-      this.adopt(payload);
-      return this;
-    } finally {
-      this.saving = false;
-    }
-  }
-  async refresh(options = {}) {
-    const payload = await this.context.transport.json({
-      method: "GET",
-      path: ApiPath.entry(this.context.project, this.context.environment, this.context.collection, this.id),
-      query: { variables: "raw" },
-      ...options
-    });
-    this.adopt(payload);
-    return this;
-  }
-  adopt(payload) {
-    this.rev = Number(payload.rev);
-    this.createdAt = new Date(payload.created_at);
-    this.updatedAt = new Date(payload.updated_at);
-    this.fields = EntryMapper.fieldsOf(payload);
-  }
-}
-
 // src/transport/page-payload.ts
 class PagePayload {
   static read(body) {
@@ -929,40 +835,39 @@ class EntryStream extends RowStream {
 
 // src/entries/entry-reader.ts
 class EntryReader {
-  context;
-  variables;
-  wrap;
-  constructor(context, variables, wrap) {
-    this.context = context;
-    this.variables = variables;
-    this.wrap = wrap;
-  }
-  async get(id, options = {}) {
-    const payload = await this.context.transport.json({
+  scope;
+  collection;
+  constructor(scope, collection) {
+    this.scope = scope;
+    this.collection = collection;
+  }
+  get(id, options = {}) {
+    const { variables, ...request } = options;
+    return this.scope.transport.json({
       method: "GET",
-      path: ApiPath.entry(this.context.project, this.context.environment, this.context.collection, id),
-      query: { variables: this.variables },
-      ...options
+      path: ApiPath.entry(this.scope.project, this.scope.environment, this.collection, id),
+      query: { variables },
+      ...request
     });
-    return this.wrap(payload);
   }
   async list(query = {}, options = {}) {
+    const { variables, ...request } = options;
     const loader = (window2) => this.list({ ...query, limit: window2.limit, offset: window2.offset }, options);
-    const body = await this.context.transport.json({
+    const body = await this.scope.transport.json({
       method: "GET",
-      path: ApiPath.entries(this.context.project, this.context.environment, this.context.collection),
+      path: ApiPath.entries(this.scope.project, this.scope.environment, this.collection),
       query: {
         limit: query.limit,
         offset: query.offset,
         filter: query.where?.toJSON(),
         sort: query.sort === undefined ? undefined : String(query.sort),
-        variables: this.variables
+        variables
       },
-      ...options
+      ...request
     });
     const page = PagePayload.read(body);
     const window = new PageWindow(page.limit ?? query.limit ?? 50, page.offset ?? query.offset ?? 0);
-    return new EntryPage(page.rows.map((payload) => this.wrap(payload)), page.total, window, loader);
+    return new EntryPage(page.rows, page.total, window, loader);
   }
   all(query = {}, options = {}) {
     const loader = async (window) => {
@@ -1136,15 +1041,15 @@ class Search {
     const window = new PageWindow(page.limit ?? query.limit ?? 50, page.offset ?? query.offset ?? 0);
     const truncated = body.truncated === true;
     const engine = body.engine;
-    const hits = page.rows.map((hit) => this.toHit(hit));
+    const hits = page.rows.map((hit) => Search.toHit(hit));
     return new SearchPage(hits, page.total, window, truncated, engine, loader);
   }
-  toHit(payload) {
+  static toHit(payload) {
     return {
       project: payload.project,
       environment: payload.env,
       collection: payload.collection,
-      entry: new ResolvedEntry({ transport: this.transport, project: payload.project, environment: payload.env, collection: payload.collection }, payload.entry),
+      entry: payload.entry,
       snippets: payload.snippets
     };
   }
@@ -1207,36 +1112,24 @@ class CollectionHandle {
   name;
   filter = new TypedFilter;
   schema;
-  editable;
-  context;
-  resolved;
+  reader;
   constructor(scope, name) {
     this.scope = scope;
     this.name = name;
     this.schema = new CollectionSchema(scope, name);
-    this.context = {
-      transport: scope.transport,
-      project: scope.project,
-      environment: scope.environment,
-      collection: name
-    };
-    this.resolved = new EntryReader(this.context, undefined, (payload) => new ResolvedEntry(this.context, payload));
-    this.editable = new EntryReader(this.context, "raw", (payload) => new Entry(this.context, payload));
+    this.reader = new EntryReader(scope, name);
   }
   get(id, options = {}) {
-    return this.resolved.get(id, options);
-  }
-  edit(id, options = {}) {
-    return this.editable.get(id, options);
+    return this.reader.get(id, options);
   }
   list(query = {}, options = {}) {
-    return this.resolved.list(query, options);
+    return this.reader.list(query, options);
   }
   all(query = {}, options = {}) {
-    return this.resolved.all(query, options);
+    return this.reader.all(query, options);
   }
   pages(query = {}, options = {}) {
-    return this.resolved.pages(query, options);
+    return this.reader.pages(query, options);
   }
   create(fields, options = {}) {
     return this.write("POST", ApiPath.entries(this.scope.project, this.scope.environment, this.name), fields, undefined, options);
@@ -1266,23 +1159,14 @@ class CollectionHandle {
     });
     return RenameReport.fromWire(payload);
   }
-  async write(method, path, fields, rev, options) {
-    const payload = await this.scope.transport.json({
+  write(method, path, fields, rev, options) {
+    return this.scope.transport.json({
       method,
       path,
       query: { rev, variables: "raw" },
       body: fields,
       ...options
     });
-    return new Entry(this.context, payload);
-  }
-}
-
-// src/collections/reserved-field-names.ts
-class ReservedFieldNames {
-  static all = ["id", "rev", "seq", "created_at", "updated_at"];
-  static isReserved(name) {
-    return ReservedFieldNames.all.includes(name);
   }
 }
 
@@ -1301,7 +1185,6 @@ class Collections {
     return body.items.map(Collections.toSummary);
   }
   async create(name, schema, options = {}) {
-    Collections.warnOnReservedFields(schema);
     return this.scope.transport.json({
       method: "POST",
       path: ApiPath.collections(this.scope.project, this.scope.environment),
@@ -1319,13 +1202,6 @@ class Collections {
       updatedAt: new Date(payload.updated_at)
     };
   }
-  static warnOnReservedFields(schema) {
-    for (const name of Object.keys(schema.properties ?? {})) {
-      if (ReservedFieldNames.isReserved(name)) {
-        console.warn(`@org-quicko/silo-client: collection schema declares reserved field "${name}", which the server never returns`);
-      }
-    }
-  }
 }
 
 // src/variables/environment-variables.ts

package/dist/index.d.cts

@@ -21,19 +21,17 @@ export type { DeleteOptions } from "./scope/delete-options.cjs";
 export { Collections } from "./collections/collections.cjs";
 export { CollectionHandle } from "./collections/collection-handle.cjs";
 export { CollectionSchema } from "./collections/collection-schema.cjs";
-export { ReservedFieldNames } from "./collections/reserved-field-names.cjs";
 export type { CollectionSummary } from "./collections/collection-summary.cjs";
 export type { CollectionDefinition } from "./collections/collection-definition.cjs";
 export type { JsonSchema } from "./collections/json-schema.cjs";
-export { EntryBase } from "./entries/entry-base.cjs";
-export { ResolvedEntry } from "./entries/resolved-entry.cjs";
-export { Entry } from "./entries/entry.cjs";
 export { EntryPage } from "./entries/entry-page.cjs";
 export { EntryStream } from "./entries/entry-stream.cjs";
 export { EntryPageStream } from "./entries/entry-page-stream.cjs";
 export { EntryReader } from "./entries/entry-reader.cjs";
+export type { Entry } from "./entries/entry.cjs";
+export type { EntryEnvelope } from "./entries/entry-envelope.cjs";
 export type { EntryListQuery } from "./entries/entry-list-query.cjs";
-export type { EntryPayload } from "./entries/entry-payload.cjs";
+export type { EntryReadOptions } from "./entries/entry-read-options.cjs";
 export { Filter } from "./query/filter.cjs";
 export { TypedFilter } from "./query/typed-filter.cjs";
 export { FilterField } from "./query/filter-field.cjs";

package/dist/index.d.ts

@@ -21,19 +21,17 @@ export type { DeleteOptions } from "./scope/delete-options.js";
 export { Collections } from "./collections/collections.js";
 export { CollectionHandle } from "./collections/collection-handle.js";
 export { CollectionSchema } from "./collections/collection-schema.js";
-export { ReservedFieldNames } from "./collections/reserved-field-names.js";
 export type { CollectionSummary } from "./collections/collection-summary.js";
 export type { CollectionDefinition } from "./collections/collection-definition.js";
 export type { JsonSchema } from "./collections/json-schema.js";
-export { EntryBase } from "./entries/entry-base.js";
-export { ResolvedEntry } from "./entries/resolved-entry.js";
-export { Entry } from "./entries/entry.js";
 export { EntryPage } from "./entries/entry-page.js";
 export { EntryStream } from "./entries/entry-stream.js";
 export { EntryPageStream } from "./entries/entry-page-stream.js";
 export { EntryReader } from "./entries/entry-reader.js";
+export type { Entry } from "./entries/entry.js";
+export type { EntryEnvelope } from "./entries/entry-envelope.js";
 export type { EntryListQuery } from "./entries/entry-list-query.js";
-export type { EntryPayload } from "./entries/entry-payload.js";
+export type { EntryReadOptions } from "./entries/entry-read-options.js";
 export { Filter } from "./query/filter.js";
 export { TypedFilter } from "./query/typed-filter.js";
 export { FilterField } from "./query/filter-field.js";