@venizia/ignis-connectors/http
Generated from the built declarations by
vulcan x atlas api gen- do not edit.
15 exports, 15 with TSDoc. 2 more are re-exported from other entries (listed at the end).
HttpDataSource
class
Reads an IGNIS REST server through the repository contract. Targets IGNIS, not any REST API.
export declare class HttpDataSource extends DataSourceRoot<IHttpDataSourceSettings> {
name: string;
settings: IHttpDataSourceSettings;
schema: never;
/** Normalised once: every request copies these, never re-parses `settings.headers`. */
protected configuredHeaders: Headers;
constructor(opts: IHttpDataSourceSettings & {
name?: string;
});
configure(): Promise<void>;
getCapabilities(): {
transactions: boolean;
};
protected resolveAuthToken(opts: {
context: IHttpRequestContext;
}): IAuthToken | undefined;
/** Re-run on every send, so a header the app changed since the last request is the one sent. */
protected resolveHeaders(opts: {
context: IHttpRequestContext;
}): Headers;
protected buildHeaders(opts: {
token?: IAuthToken;
requestHeaders?: Headers;
isJsonBody?: boolean;
isFormDataBody?: boolean;
}): Headers;
buildUrl(opts: {
paths: Array<string>;
query?: Record<string, unknown>;
}): string;
/**
* The raw `Response`, on any method - for what the repository verbs do not cover, like an export
* or a PUT to a hand-written route. Auth and the 401 retry apply; the retry resends the same body.
*/
request(opts: {
paths: Array<string>;
query?: Record<string, unknown>;
method?: string;
body?: THttpBody;
} & IHttpCallOptions): Promise<Response>;
/** `request` on a URL already built: `read` and `write` serialise a long query once, not per use. */
protected sendRequest(opts: {
paths: Array<string>;
url: string;
method?: string;
body?: THttpBody;
} & IHttpCallOptions): Promise<Response>;
/**
* The body as JSON, `null` when there is none; a body that is not JSON is the server's fault, named
* as such. Its content stays out of the message, which a relaying server may pass to its clients.
*/
protected readJsonBody(opts: {
response: Response;
url: string;
verb: string;
}): Promise<import("@venizia/ignis-helpers").TJsonValue>;
/**
* A failed response as the error the server threw: its status, code, args and text, and its
* `extra` with the `requestId` added. `message` adds where it failed, for logs; `normalized.text`
* stays the server's, for display - `HTTP <status>` when the server sent none. `cause` is the server's `details.cause` - a 422's per-field
* issues, `{ path, message, code }`.
*/
protected toResponseError(opts: {
response: Response;
url: string;
verb: string;
}): Promise<import("@venizia/ignis-inversion").ApplicationError>;
/**
* Rows plus the total from `Content-Range`, reported absent when the header is. A GET unless told
* otherwise: `method` and `body` reach a list route a service wrote to take its filter in a body.
*/
read<R>(opts: {
paths: Array<string>;
query?: Record<string, unknown>;
shape?: THttpReadShape;
method?: string;
body?: THttpBody;
/** Extras the route offers beside its rows, asked for by name (`x-request-extra`). */
extra?: TExtraRequest;
/** The rows alone: every default extra off (`-*`), for a read that only counts or probes. */
isEveryDefaultOff?: boolean;
} & IHttpCallOptions): Promise<IHttpReadResult<R>>;
/**
* A write, and what it answered: the body as the rows, the count from `x-response-count`. The
* connector asks for bare rows, so an IGNIS write answers the row or the rows, never the envelope.
*/
write<R>(opts: {
paths: Array<string>;
query?: Record<string, unknown>;
method: string;
body?: THttpBody;
/** Extras the route answers beside its rows, asked for by name (`x-request-extra`). */
extra?: TExtraRequest;
} & IHttpCallOptions): Promise<IHttpWriteResult<R>>;
}Source: packages/connectors/src/http/datasource.ts
HttpReadShapes
class
What a read expects back: LIST (a bare array or the { count, data } envelope) or ONE (a single record, never unwrapped).
export declare class HttpReadShapes extends ConstClass {
static readonly LIST = "list";
static readonly ONE = "one";
}Source: packages/connectors/src/http/common/constants.ts
HttpRepository
class
One remote resource, read and written through the IGNIS CRUD routes, in the @venizia/ignis-filter vocabulary. P is what a write sends - a partial row by default, since the server fills ids and defaults. There is no createAll: the IGNIS REST contract has no bulk-create route.
export declare class HttpRepository<E extends object = object, P extends object = Partial<E>> implements IReadableRepository<E, THttpRepositoryOptions>, IUpdatableRepository<E, P, THttpRepositoryOptions>, IDeletableRepository<E, THttpRepositoryOptions> {
dataSource: HttpDataSource;
entity: AbstractEntity;
protected resource: string;
/** A count route, if the API has one. Absent, the total comes from `Content-Range`. */
protected countPath?: string;
/** The segment after the resource that names the IGNIS find-one route. Absent, `findOne` asks the list route for one row. */
protected findOnePath?: string;
/** The page size `find` asks for when its filter names no limit. Absent, the server's own default applies. */
protected defaultLimit?: number;
/**
* The segment after the resource that names the IGNIS search route.
*
* @default 'search'
*/
protected searchPath: string;
constructor(opts: {
dataSource: HttpDataSource;
resource: string;
countPath?: string;
findOnePath?: string;
defaultLimit?: number;
searchPath?: string;
});
getEntity(): AbstractEntity;
/**
* The query string of a read: the caller's extra `query` with the call's own `params` (`filter`,
* `where`) over it. `method` names the repository verb, so a subclass can reshape one route - a
* keyword into the object its server reads - and leave the others.
*/
protected buildQuery(opts: {
method: string;
query?: THttpExtraQuery;
params: Record<string, unknown>;
}): Record<string, unknown>;
/** The filter `find` sends: the caller's, with `defaultLimit` filled in when it names no limit. */
protected resolveFindFilter(opts: {
filter?: TFilter<E>;
}): TFilter<E>;
/** `<resource>/<searchPath>`; override to move the route. */
protected getSearchPaths(): Array<string>;
/** No header and an unreadable one (`/*`) have different fixes, so different messages. */
protected getMissingTotalError(opts: {
method: string;
contentRange?: string;
noHeader: string;
}): import("@venizia/ignis-inversion").ApplicationError;
/** From `Content-Range`, or `countPath`. No total throws rather than reporting the page size. */
count(opts: {
where: TWhere<E>;
query?: THttpExtraQuery;
options?: THttpRepositoryOptions;
}): Promise<TCount>;
existsWith(opts: {
where: TWhere<E>;
query?: THttpExtraQuery;
options?: THttpRepositoryOptions;
}): Promise<boolean>;
/** With `extra`: what the route answered beside the rows, typed by what was asked for. */
find<R = unknown, const Extra extends TExtraRequest = TExtraRequest, const F extends TFields<E> = TFields<E>>(opts: {
filter: TFilter<E, F>;
query?: THttpExtraQuery;
options: THttpRepositoryOptions & {
shouldQueryRange: true;
extra: Extra;
};
}): Promise<TDataWithRange<TRow<E, R, F>> & {
extra: TExtraResult<Extra>;
}>;
find<R = unknown, const F extends TFields<E> = TFields<E>>(opts: {
filter: TFilter<E, F>;
query?: THttpExtraQuery;
options: THttpRepositoryOptions & {
shouldQueryRange: true;
};
}): Promise<TDataWithRange<TRow<E, R, F>>>;
find<R = unknown, const Extra extends TExtraRequest = TExtraRequest, const F extends TFields<E> = TFields<E>>(opts: {
filter?: TFilter<E, F>;
query?: THttpExtraQuery;
options: THttpRepositoryOptions & {
extra: Extra;
};
}): Promise<{
data: Array<TRow<E, R, F>>;
extra: TExtraResult<Extra>;
}>;
find<R = unknown, const F extends TFields<E> = TFields<E>>(opts: {
filter?: TFilter<E, F>;
query?: THttpExtraQuery;
options?: THttpRepositoryOptions;
}): Promise<Array<TRow<E, R, F>>>;
/** `extra` or the range decided at run time: the caller narrows the union. */
find<R = unknown, const F extends TFields<E> = TFields<E>>(opts: {
filter?: TFilter<E, F>;
query?: THttpExtraQuery;
options?: THttpRepositoryOptions & {
shouldQueryRange?: boolean;
extra?: TExtraRequest;
};
}): Promise<Array<TRow<E, R, F>> | TDataWithRange<TRow<E, R, F>> | {
data: Array<TRow<E, R, F>>;
extra: TExtraResult<TExtraRequest>;
}>;
findOne<R = unknown, const F extends TFields<E> = TFields<E>>(opts: {
filter?: TFilter<E, F>;
query?: THttpExtraQuery;
options?: THttpRepositoryOptions;
}): Promise<TRow<E, R, F> | null>;
/** The server answers `null`, never 404, for a missing id. A `where` would be replaced by the id. */
findById<R = unknown, const F extends TFields<E> = TFields<E>>(opts: {
id: string | number;
filter?: TByIdFilter<E, F>;
query?: THttpExtraQuery;
options?: THttpRepositoryOptions;
}): Promise<TRow<E, R, F> | null>;
/**
* POST `<resource>/search`, the IGNIS search route: `input` is its body (a keyword, semantic, hybrid
* or raw search), the answer its `{ found, isFoundExact, hits }`. `found` is the total - there is no
* count route for a search, and `isFoundExact` says when it is an estimate.
*/
search<R extends object = E>(opts: {
input: TSearchInput;
query?: THttpExtraQuery;
options?: THttpRepositoryOptions;
}): Promise<IHttpSearchResult<R>>;
/**
* `<resource>/<id>`, the id encoded: an id carrying `/` or `?` would otherwise name another route.
* An empty, `.` or `..` id is refused: a URL resolves it, encoded or not, to `/<resource>/` or the
* parent - a router or proxy that ignores the trailing slash then serves the list or bulk route.
*/
protected getIdPaths(opts: {
id: string | number;
}): Array<string>;
/** What a call adds to its request: headers and an abort signal. Every other option stays local. */
protected toCallOptions(opts: {
options?: THttpRepositoryOptions;
}): IHttpCallOptions;
/** The IGNIS bulk routes answer an empty `where` with a 400; refused here before a request is spent. */
protected assertBulkWhere(opts: {
method: string;
where?: TWhere<E>;
}): TWhere<E>;
/** The server always answers the rows; `shouldReturn: false` drops them here, as a database repository would not fetch them. */
protected toWriteResult<R>(opts: {
result: IHttpWriteResult<R>;
options?: THttpRepositoryOptions & {
shouldReturn?: boolean;
};
}): TCount & {
data: R | null;
};
/** POST `/<resource>`. */
create<R = E>(opts: {
data: P;
options?: THttpRepositoryOptions & {
shouldReturn?: true;
};
}): Promise<TCount & {
data: R;
}>;
updateById(opts: {
id: string | number;
data: Partial<P>;
options: THttpRepositoryOptions & {
shouldReturn: false;
};
}): Promise<TCount & {
data: undefined | null;
}>;
updateById<R = E>(opts: {
id: string | number;
data: Partial<P>;
options?: THttpRepositoryOptions & {
shouldReturn?: true;
};
}): Promise<TCount & {
data: R;
}>;
updateBy(opts: {
data: Partial<P>;
where: TWhere<E>;
options: THttpRepositoryOptions & {
shouldReturn: false;
force?: boolean;
};
}): Promise<TCount & {
data: undefined | null;
}>;
updateBy<R = E>(opts: {
data: Partial<P>;
where: TWhere<E>;
options?: THttpRepositoryOptions & {
shouldReturn?: true;
force?: boolean;
};
}): Promise<TCount & {
data: Array<R> | null;
}>;
protected patchWhere(opts: {
method: string;
data: Partial<P>;
where: TWhere<E>;
options?: THttpRepositoryOptions & {
shouldReturn?: boolean;
};
}): Promise<TCount & {
data: unknown;
}>;
deleteById(opts: {
id: string | number;
options: THttpRepositoryOptions & {
shouldReturn: false;
};
}): Promise<TCount & {
data: undefined | null;
}>;
deleteById<R = E>(opts: {
id: string | number;
options?: THttpRepositoryOptions & {
shouldReturn?: true;
};
}): Promise<TCount & {
data: R;
}>;
deleteBy(opts: {
where: TWhere<E>;
options: THttpRepositoryOptions & {
shouldReturn: false;
force?: boolean;
};
}): Promise<TCount & {
data: undefined | null;
}>;
deleteBy<R = E>(opts: {
where: TWhere<E>;
options?: THttpRepositoryOptions & {
shouldReturn?: true;
force?: boolean;
};
}): Promise<TCount & {
data: Array<R> | null;
}>;
protected deleteWhere(opts: {
method: string;
where: TWhere<E>;
options?: THttpRepositoryOptions & {
shouldReturn?: boolean;
};
}): Promise<TCount & {
data: unknown;
}>;
}
/**
* What a repository call takes. Only `headers` and `signal` cross HTTP; the shared repository
* options (`transaction`, `log`, ...) are accepted for the common contract and have no effect.
*/
type THttpRepositoryOptions = NonNullable<Parameters<IReadableRepository['existsWith']>[0]['options']> & IHttpCallOptions;Source: packages/connectors/src/http/repository.ts
IAuthToken
interface
A credential the HTTP datasource attaches to a request: Authorization: <type> <value>, and provider, when set, as the x-auth-provider header.
export interface IAuthToken {
value: string;
/**
* The authorization scheme.
*
* @default 'Bearer'
*/
type?: string;
provider?: string;
}Source: packages/connectors/src/http/common/types.ts
IHttpCallOptions
interface
What one call may add: its own headers (they win over the configured ones) and a signal to abort it.
export interface IHttpCallOptions {
headers?: THttpHeaders;
signal?: AbortSignal;
}Source: packages/connectors/src/http/common/types.ts
IHttpDataSourceSettings
interface
Settings of the HTTP datasource: where to send, which headers and token to attach, and what to do on a 401.
export interface IHttpDataSourceSettings {
/** An absolute URL, or a path from the page origin (`/api`). A path-relative one is refused. */
baseUrl: string;
/** The server's `error.rootKey`: an error envelope wrapped under it is unwrapped before it is read. */
errorRootKey?: string;
/** Sent on every request. `x-request-count` is refused - the connector owns it. */
headers?: THttpHeaders;
/**
* Headers for this request, run on every send (the 401 retry included); wins over `headers`, a call's own win over it. A throw
* fails the request; `x-request-count` is refused, and an `authorization` stands only when no token resolves.
*/
headersResolver?: (context: IHttpRequestContext) => THttpHeaders | undefined;
/** Wins over `authTokenResolver`, and is sent whatever the request. */
authToken?: IAuthToken;
/** Run on every send, the 401 retry included. `undefined` means no token for this request. A throw fails the request with that error. */
authTokenResolver?: (context: IHttpRequestContext) => IAuthToken | undefined;
/** Runs on a 401: `true` retries once (re-resolving the token), `false` lets the 401 stand. `context` is the object the resolvers got for this call; `info.attempt` says which send failed. */
onUnauthorized?: (context: IHttpRequestContext, info: IHttpUnauthorizedInfo) => Promise<boolean> | boolean;
/** What sends a request: the platform `fetch` when unset. Name one to route through a test double, a proxy or an instrumented client. */
fetch?: THttpFetch;
}Source: packages/connectors/src/http/common/types.ts
IHttpReadResult
interface
A list with no Content-Range has no total - hasRange says so rather than using the page size.
export interface IHttpReadResult<R> {
data: R;
hasRange: boolean;
/** Raw header: tells a present-but-unreadable one from an absent one. */
contentRange?: string;
total?: number;
skip?: number;
dataLength: number;
/** What a list answered beside its rows, when the server marked it with `x-response-extra`. */
extra?: Record<string, unknown>;
}Source: packages/connectors/src/http/common/types.ts
IHttpRequestContext
interface
The request a hook is asked about, the SAME object for every hook and every send of one call (a session map may key on it): the repository paths, the method, and the final URL with its query.
export interface IHttpRequestContext {
paths: Array<string>;
method: string;
url: string;
/** The call's own signal: a hook may stop waiting on it. A refresh shared by other calls should not be aborted by one. */
signal?: AbortSignal;
}Source: packages/connectors/src/http/common/types.ts
IHttpSearchResult
interface
What the IGNIS search route answers: the total as found (isFoundExact is false when it is an estimate) and the hits.
export interface IHttpSearchResult<R> {
found: number;
isFoundExact: boolean;
hits: Array<{
document: R;
score?: number;
highlight?: unknown;
highlights?: Array<unknown>;
}>;
}Source: packages/connectors/src/http/common/types.ts
IHttpUnauthorizedInfo
interface
What onUnauthorized is told besides the request: attempt is 1 for the first 401, 2 for the retry's own.
export interface IHttpUnauthorizedInfo {
attempt: number;
}Source: packages/connectors/src/http/common/types.ts
IHttpWriteResult
interface
What a write answers: the rows the server returned, and its x-response-count.
export interface IHttpWriteResult<R> {
data: R;
count: number;
/** What the route answered beside the rows, when the server marked it with `x-response-extra`. */
extra?: Record<string, unknown>;
}Source: packages/connectors/src/http/common/types.ts
THttpBody
type
A request body. A plain object or array goes out as JSON; a string, Blob, FormData, URLSearchParams, ArrayBuffer or typed array goes out as it is. Never a stream: the 401 retry sends the same body twice.
export type THttpBody = string | object;Source: packages/connectors/src/http/common/types.ts
THttpExtraQuery
type
Query parameters a route takes beside filter or where - a keyword, a scope. The filter and where win over a key of the same name.
export type THttpExtraQuery = Record<string, unknown>;Source: packages/connectors/src/http/common/types.ts
THttpFetch
type
What sends a request: a URL and its init, a Response back. The public name of the sender type.
export type THttpFetch = TNativeFetchSender;Source: packages/connectors/src/http/common/types.ts
THttpReadShape
type
Valid HTTP read shape values.
export type THttpReadShape = TConstValue<typeof HttpReadShapes>;Source: packages/connectors/src/http/common/constants.ts
Re-exported
TExtraRequestfrom@venizia/ignis-kernel/repositoryTExtraResultfrom@venizia/ignis-kernel/repository