lingcode-backend 0.1.0

package/index.d.ts

@@ -0,0 +1,149 @@
+// Type definitions for lingcode-backend
+
+declare const idBrand: unique symbol;
+/** A row id branded with its table. At runtime it is a string. */
+export type Id<TableName extends string> = string & { readonly [idBrand]: TableName };
+
+export interface Validator<T, IsOptional extends boolean = false> {
+  readonly json: { type: string; [key: string]: unknown };
+  readonly isOptional: IsOptional;
+  /** Type-only marker. */
+  readonly __type?: T;
+}
+
+export type Infer<V> = V extends Validator<infer T, any> ? T : never;
+
+type OptionalKeys<F> = { [K in keyof F]: F[K] extends Validator<any, true> ? K : never }[keyof F];
+type RequiredKeys<F> = Exclude<keyof F, OptionalKeys<F>>;
+type Simplify<T> = { [K in keyof T]: T[K] } & {};
+
+export type ObjectType<F extends Record<string, Validator<any, boolean>>> = Simplify<
+  { [K in RequiredKeys<F>]: Infer<F[K]> } & { [K in OptionalKeys<F>]?: Infer<F[K]> }
+>;
+
+export interface StringOptions { minLength?: number; maxLength?: number }
+export interface NumberOptions { integer?: boolean; min?: number; max?: number }
+
+export declare const v: {
+  string(opts?: StringOptions): Validator<string>;
+  number(opts?: NumberOptions): Validator<number>;
+  int(opts?: Omit<NumberOptions, 'integer'>): Validator<number>;
+  boolean(): Validator<boolean>;
+  null(): Validator<null>;
+  any(): Validator<any>;
+  id<TableName extends string>(table: TableName): Validator<Id<TableName>>;
+  /** An ISO 8601 date-time string. */
+  timestamp(): Validator<string>;
+  literal<T extends string | number | boolean | null>(value: T): Validator<T>;
+  array<T>(items: Validator<T>, opts?: { maxItems?: number }): Validator<T[]>;
+  object<F extends Record<string, Validator<any, boolean>>>(fields: F): Validator<ObjectType<F>>;
+  record<T>(values: Validator<T>): Validator<Record<string, T>>;
+  union<M extends Validator<any>[]>(...members: M): Validator<Infer<M[number]>>;
+  optional<T>(inner: Validator<T>): Validator<T, true>;
+};
+
+export declare const string: typeof v.string;
+export declare const number: typeof v.number;
+export declare const int: typeof v.int;
+export declare const boolean: typeof v.boolean;
+export declare const nullValue: typeof v.null;
+export declare const any: typeof v.any;
+export declare const id: typeof v.id;
+export declare const timestamp: typeof v.timestamp;
+export declare const literal: typeof v.literal;
+export declare const array: typeof v.array;
+export declare const object: typeof v.object;
+export declare const record: typeof v.record;
+export declare const union: typeof v.union;
+export declare const optional: typeof v.optional;
+
+export interface QueryResult<Row = Record<string, any>> {
+  rows: Row[];
+  rowCount: number | null;
+  fields: string[];
+}
+
+export interface DatabaseReader {
+  /** Run one parameterized SQL statement ($1, $2, …) inside the function's transaction. */
+  query<Row = Record<string, any>>(sql: string, params?: unknown[]): Promise<QueryResult<Row>>;
+}
+
+export interface Auth {
+  /** The signed-in user's id, or null for an anonymous caller. */
+  userId: string | null;
+}
+
+export interface QueryCtx {
+  /** Read-only, repeatable-read snapshot. Writes fail. */
+  db: DatabaseReader;
+  auth: Auth;
+}
+
+export interface MutationCtx {
+  /** One serializable transaction for the whole handler. */
+  db: DatabaseReader;
+  auth: Auth;
+}
+
+export interface ActionCtx {
+  auth: Auth;
+  /** Values of the secrets this action declares. */
+  secrets: Record<string, string>;
+  runQuery<F extends RegisteredQuery<any, any>>(ref: FunctionReference<'query', F>, args: FunctionArgs<F>): Promise<FunctionReturnType<F>>;
+  runMutation<F extends RegisteredMutation<any, any>>(ref: FunctionReference<'mutation', F>, args: FunctionArgs<F>): Promise<FunctionReturnType<F>>;
+}
+
+type ArgsFor<A extends Record<string, Validator<any, boolean>>> = ObjectType<A>;
+
+export interface RegisteredQuery<Args, Returns> {
+  readonly handler: (ctx: QueryCtx, args: Args) => Returns | Promise<Returns>;
+  readonly __kind?: 'query';
+}
+export interface RegisteredMutation<Args, Returns> {
+  readonly handler: (ctx: MutationCtx, args: Args) => Returns | Promise<Returns>;
+  readonly __kind?: 'mutation';
+}
+export interface RegisteredAction<Args, Returns> {
+  readonly handler: (ctx: ActionCtx, args: Args) => Returns | Promise<Returns>;
+  readonly __kind?: 'action';
+}
+
+type AnyRegistered = RegisteredQuery<any, any> | RegisteredMutation<any, any> | RegisteredAction<any, any>;
+
+export type FunctionArgs<F> = F extends { handler: (ctx: any, args: infer A) => any } ? A : never;
+export type FunctionReturnType<F> = F extends { handler: (ctx: any, args: any) => infer R } ? Awaited<R> : never;
+
+/** A reference to a deployed function, from lingcode/_generated/api. */
+export interface FunctionReference<Kind extends 'query' | 'mutation' | 'action', F extends AnyRegistered = AnyRegistered> {
+  readonly _path: string;
+  readonly _kind: Kind;
+  readonly __function?: F;
+}
+
+export declare function query<A extends Record<string, Validator<any, boolean>>, R>(definition: {
+  args: A;
+  returns?: Validator<R>;
+  handler: (ctx: QueryCtx, args: ArgsFor<A>) => R | Promise<R>;
+}): RegisteredQuery<ArgsFor<A>, R> & { readonly __kind?: 'query' };
+
+export declare function mutation<A extends Record<string, Validator<any, boolean>>, R>(definition: {
+  args: A;
+  returns?: Validator<R>;
+  handler: (ctx: MutationCtx, args: ArgsFor<A>) => R | Promise<R>;
+}): RegisteredMutation<ArgsFor<A>, R> & { readonly __kind?: 'mutation' };
+
+export declare function action<A extends Record<string, Validator<any, boolean>>, R>(definition: {
+  args: A;
+  returns?: Validator<R>;
+  /** Names of secrets this action may read through ctx.secrets. */
+  secrets?: string[];
+  handler: (ctx: ActionCtx, args: ArgsFor<A>) => R | Promise<R>;
+}): RegisteredAction<ArgsFor<A>, R> & { readonly __kind?: 'action' };
+
+export declare class LingCodeError<Data = unknown> extends Error {
+  constructor(code: string, options?: { message?: string; data?: Data });
+  readonly code: string;
+  readonly data: Data | null;
+}
+
+export declare function isLingCodeError(error: unknown, code?: string): error is LingCodeError;

package/index.js

@@ -0,0 +1,130 @@
+// lingcode-backend — define named backend functions.
+//
+// This module is bundled into every deployed backend module, so it has no
+// dependencies. Validators here only DESCRIBE values as JSON; the LingCode
+// server enforces them (website/server/cloud-validators.js) before a handler
+// runs and on the value it returns.
+
+const MARK = '__lingcode';
+
+class Validator {
+  constructor(json, optional = false) {
+    this.json = json;
+    this.isOptional = optional;
+    Object.freeze(this);
+  }
+}
+
+function validator(value, label) {
+  if (!(value instanceof Validator) && !(value && value.json && typeof value.json.type === 'string')) {
+    throw new TypeError(`${label} must be a validator such as v.string()`);
+  }
+  return value;
+}
+
+function fieldsJson(fields, label) {
+  if (!fields || typeof fields !== 'object' || Array.isArray(fields)) throw new TypeError(`${label} must be an object of validators`);
+  const out = {};
+  for (const [key, value] of Object.entries(fields)) {
+    const val = validator(value, `${label}.${key}`);
+    out[key] = val.isOptional ? { type: 'optional', inner: val.json } : val.json;
+  }
+  return out;
+}
+
+function numberOpts(opts) {
+  const out = {};
+  if (opts) {
+    if (opts.integer) out.integer = true;
+    if (opts.min !== undefined) out.min = opts.min;
+    if (opts.max !== undefined) out.max = opts.max;
+  }
+  return out;
+}
+
+export const v = Object.freeze({
+  string: (opts) => new Validator({
+    type: 'string',
+    ...(opts && opts.minLength !== undefined ? { minLength: opts.minLength } : {}),
+    ...(opts && opts.maxLength !== undefined ? { maxLength: opts.maxLength } : {}),
+  }),
+  number: (opts) => new Validator({ type: 'number', ...numberOpts(opts) }),
+  int: (opts) => new Validator({ type: 'number', ...numberOpts(opts), integer: true }),
+  boolean: () => new Validator({ type: 'boolean' }),
+  null: () => new Validator({ type: 'null' }),
+  any: () => new Validator({ type: 'any' }),
+  id: (table) => {
+    if (typeof table !== 'string' || !table) throw new TypeError('v.id(table) needs a table name');
+    return new Validator({ type: 'id', table });
+  },
+  timestamp: () => new Validator({ type: 'timestamp' }),
+  literal: (value) => {
+    if (value !== null && !['string', 'number', 'boolean'].includes(typeof value)) {
+      throw new TypeError('v.literal() takes a string, number, boolean, or null');
+    }
+    return new Validator({ type: 'literal', value });
+  },
+  array: (items, opts) => new Validator({
+    type: 'array',
+    items: validator(items, 'v.array() items').json,
+    ...(opts && opts.maxItems !== undefined ? { maxItems: opts.maxItems } : {}),
+  }),
+  object: (fields) => new Validator({ type: 'object', fields: fieldsJson(fields, 'v.object()') }),
+  record: (values) => new Validator({ type: 'record', values: validator(values, 'v.record() values').json }),
+  union: (...members) => {
+    if (!members.length) throw new TypeError('v.union() needs at least one member');
+    return new Validator({ type: 'union', members: members.map((m, i) => validator(m, `v.union() member ${i}`).json) });
+  },
+  optional: (inner) => new Validator(validator(inner, 'v.optional()').json, true),
+});
+
+export const {
+  string, number, int, boolean, any, id, timestamp, literal, array, object, record, union, optional,
+} = v;
+export const nullValue = v.null;
+
+function define(kind, definition) {
+  if (!definition || typeof definition !== 'object') throw new TypeError(`${kind}() takes { args, handler }`);
+  if (typeof definition.handler !== 'function') throw new TypeError(`${kind}() needs a handler(ctx, args) function`);
+  if (!definition.args || typeof definition.args !== 'object') {
+    throw new TypeError(`${kind}() needs args: an object of validators (use args: {} for none)`);
+  }
+  const spec = {
+    kind,
+    args: fieldsJson(definition.args, `${kind}() args`),
+    returns: definition.returns ? validator(definition.returns, `${kind}() returns`).json : null,
+  };
+  if (kind === 'action') {
+    const secrets = definition.secrets === undefined ? [] : definition.secrets;
+    if (!Array.isArray(secrets) || secrets.some((s) => typeof s !== 'string' || !/^[A-Z][A-Z0-9_]{0,63}$/.test(s))) {
+      throw new TypeError('action() secrets must be an array of names like "STRIPE_SECRET_KEY"');
+    }
+    spec.secrets = [...new Set(secrets)];
+  } else if (definition.secrets !== undefined) {
+    throw new TypeError(`${kind}() can't read secrets; only actions can`);
+  }
+  const registered = { handler: definition.handler };
+  Object.defineProperty(registered, MARK, { value: Object.freeze(spec), enumerable: false });
+  return Object.freeze(registered);
+}
+
+export const query = (definition) => define('query', definition);
+export const mutation = (definition) => define('mutation', definition);
+export const action = (definition) => define('action', definition);
+
+// An error meant for the application: its code, message, and data reach the
+// caller unchanged in production. Any other thrown error is reported as an
+// internal error there, and its details stay in the backend logs.
+export class LingCodeError extends Error {
+  constructor(code, { message, data } = {}) {
+    super(message || String(code));
+    this.name = 'LingCodeError';
+    this.code = String(code);
+    this.data = data === undefined ? null : data;
+    this.__lingcodeError = true;
+  }
+}
+
+export function isLingCodeError(error, code) {
+  return !!(error && error.__lingcodeError === true && (code === undefined || error.code === code));
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "lingcode-backend",
+  "version": "0.1.0",
+  "description": "Define LingCode Cloud queries, mutations, and actions with runtime-validated, typed arguments.",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "keywords": ["lingcode", "backend", "query", "mutation", "reactive"],
+  "homepage": "https://lingcode.dev/docs/cloud/functions/queries.html",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Xavierhuang/LingCode.git",
+    "directory": "packages/backend"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}