@org-quicko/silo-client 1.0.0 → 1.1.0

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/errors/network-error.d.cts

@@ -8,4 +8,9 @@ export declare class NetworkError extends Error {
     readonly method: string;
     readonly path: string;
     constructor(method: string, path: string, cause: unknown);
+    /** What `fetch` rejected with, in the message itself: a `cause` chain is
+     * printed by some consoles and by no log line, and "never reached the
+     * server" alone reads as a verdict on the network when the fault can be the
+     * call. */
+    private static reason;
 }

package/dist/errors/network-error.d.ts

@@ -8,4 +8,9 @@ export declare class NetworkError extends Error {
     readonly method: string;
     readonly path: string;
     constructor(method: string, path: string, cause: unknown);
+    /** What `fetch` rejected with, in the message itself: a `cause` chain is
+     * printed by some consoles and by no log line, and "never reached the
+     * server" alone reads as a verdict on the network when the fault can be the
+     * call. */
+    private static reason;
 }