@afora/core 0.0.9 → 0.0.12

package/dist/std/blueprint-plugin.js

@@ -0,0 +1,42 @@
+import { blueprintPluginOf } from "../core/blueprint/blueprint-plugin.js";
+import { Email, Ip, Phone, Url } from "./properties/contact.js";
+import { enumOf } from "./properties/enum.js";
+import { SchemaProperty } from "./properties/headless.js";
+import { Id, Slug } from "./properties/identity.js";
+import { JsonProperty, jsonOf } from "./properties/json.js";
+import { Password } from "./properties/password.js";
+import {
+  BooleanProperty,
+  Integer,
+  NumberProperty,
+  StringProperty,
+  Text
+} from "./properties/primitives.js";
+import {
+  CreatedAt,
+  DateProperty,
+  DateTime,
+  DeletedAt,
+  UpdatedAt
+} from "./properties/time.js";
+export const Std = blueprintPluginOf("std", {
+  id: Id,
+  slug: Slug,
+  email: Email,
+  phone: Phone,
+  url: Url,
+  ip: Ip,
+  password: Password,
+  string: StringProperty,
+  text: Text,
+  number: NumberProperty,
+  integer: Integer,
+  boolean: BooleanProperty,
+  date: DateProperty,
+  dateTime: DateTime,
+  createdAt: CreatedAt,
+  updatedAt: UpdatedAt,
+  deletedAt: DeletedAt,
+  schema: SchemaProperty,
+  json: JsonProperty
+}, { enumOf, jsonOf });

package/dist/std/blueprint.d.ts

@@ -2,6 +2,27 @@
  * Builds a blueprint from the standard properties, e.g.
  * `blueprintOf((ctx) => ({ name: ctx.string }))`, and from `sources`, plugins
  * or blueprints, given before the definition, which can replace any `Std` key.
+ *
+ * @throws {@link ReservedBlueprintKey} when a source declares a key the context reserves (`optional`, `list`, `listOf`, `optionalOf`, `propertyOf`, `variantOf`).
+ *
+ * @example
+ * ```ts
+ * import { blueprintOf } from "@afora/core";
+ *
+ * const Signup = blueprintOf((ctx) => ({
+ * 	name: ctx.text,
+ * 	email: ctx.email, // trimmed and lowercased
+ * 	tags: ctx.listOf(ctx.string, { maxItems: 5 }),
+ * 	nickname: ctx.optional.string,
+ * }));
+ *
+ * const parsed = Signup.safeParse({
+ * 	name: "Ana",
+ * 	email: " ANA@example.com ",
+ * 	tags: [],
+ * });
+ * if (!parsed.issues) parsed.value.email; // "ana@example.com"
+ * ```
  */
 export declare const blueprintOf: import("../index.js").BlueprintBuilder<readonly [import("../index.js").IBlueprintPlugin<{
     id: typeof import("../index.js").Id;

package/dist/std/blueprint.js

@@ -0,0 +1,3 @@
+import { blueprintBuilderOf } from "../core/blueprint/blueprint.js";
+import { Std } from "./blueprint-plugin.js";
+export const blueprintOf = blueprintBuilderOf(Std);

package/dist/std/command.js

@@ -0,0 +1,3 @@
+import { commandBuilderOf } from "../core/command/command.js";
+import { StdUseCases } from "./use-cases/index.js";
+export const commandOf = commandBuilderOf(StdUseCases);

package/dist/std/entity.d.ts

@@ -10,7 +10,26 @@ import { CreatedAt, DeletedAt, UpdatedAt } from "./properties/time.js";
  * As a record, the class can be a field of another blueprint, e.g.
  * `{ author: User }`, with `optionalOf` and `listOf`. `options.plugins` picks
  * from the standard plugins, as `(ctx) => [ctx.publishable]`, or takes any
- * plugin made by `recordPluginOf`.
+ * plugin made by {@link recordPluginOf}.
+ *
+ * @throws {@link ReservedEntityKey} when the blueprint declares an identity key or a member of an entity.
+ * @throws {@link ReservedRecordKey} when a key of the blueprint is a member of the record.
+ *
+ * @example
+ * ```ts
+ * import { blueprintOf, entityOf } from "@afora/core";
+ *
+ * class User extends entityOf(
+ * 	blueprintOf((ctx) => ({ name: ctx.string })),
+ * 	{ change: ["name"] },
+ * ) {}
+ *
+ * const user = new User({ name: "Jane" });
+ * user.id; // a UUID v7
+ * user.updatedAt; // undefined until the first change
+ * user.change.name("Ann").updatedAt; // now
+ * user.destroy().isDeleted; // true
+ * ```
  */
 export declare const entityOf: import("../index.js").EntityBuilder<import("../core/property/types/property-options.interface.js").StoredFields<{
     id: typeof Id;

package/dist/std/entity.js

@@ -0,0 +1,30 @@
+import { blueprintBuilderOf } from "../core/blueprint/blueprint.js";
+import { entityBuilderOf } from "../core/entity/entity.js";
+import { vouching } from "../core/entity/trust.js";
+import { Id } from "./properties/identity.js";
+import { CreatedAt, DeletedAt, ExpiresAt, UpdatedAt } from "./properties/time.js";
+import { StdRecordPlugins } from "./record-plugins.js";
+import { generateId, makesDefaultIds } from "./runtime.js";
+const Identity = blueprintBuilderOf()(() => ({
+  id: Id,
+  createdAt: CreatedAt,
+  updatedAt: UpdatedAt,
+  deletedAt: DeletedAt
+}));
+let lastMillisecond = Number.NaN;
+let lastTimestamp = "";
+function now() {
+  const millisecond = Date.now();
+  if (millisecond !== lastMillisecond) {
+    lastTimestamp = new Date(millisecond).toISOString();
+    lastMillisecond = millisecond;
+  }
+  return lastTimestamp;
+}
+export const entityOf = entityBuilderOf(vouching({
+  identity: Identity,
+  generateId,
+  now,
+  expiresAt: ExpiresAt,
+  plugins: [StdRecordPlugins]
+}, { id: makesDefaultIds, createdAt: () => true }));

package/dist/std/event-policies.js

@@ -0,0 +1,3 @@
+import { eventPolicyCatalogOf } from "../core/event-policy/event-policy.js";
+import { publishEvents } from "../core/event-policy/publish.js";
+export const StdEventPolicies = eventPolicyCatalogOf(publishEvents);

package/dist/std/properties/contact.d.ts

@@ -1,6 +1,9 @@
 import { Type } from "typebox";
+/** An email address of up to 254 characters, trimmed and lowercased. */
 export declare const Email: import("../../index.js").PropertyClass<Type.TString, string>;
 /** A phone number in E.164; spaces, dots, dashes and parentheses are dropped. */
 export declare const Phone: import("../../index.js").PropertyClass<Type.TString, string>;
+/** A URL of up to 2048 characters, trimmed. */
 export declare const Url: import("../../index.js").PropertyClass<Type.TString, string>;
+/** An IPv4 or IPv6 address, trimmed. */
 export declare const Ip: import("../../index.js").PropertyClass<Type.TUnion<[Type.TString, Type.TString]>, string>;

package/dist/std/properties/contact.js

@@ -0,0 +1,29 @@
+import { Type } from "typebox";
+import { propertyOf } from "../../core/property/property.js";
+export const Email = propertyOf({
+  name: "email",
+  schema: Type.String({ format: "email", maxLength: 254 }),
+  default: "demo@example.com",
+  preHandle: (value) => value.trim().toLowerCase()
+});
+export const Phone = propertyOf({
+  name: "phone",
+  schema: Type.String({ pattern: "^\\+[1-9]\\d{1,14}$" }),
+  default: "+5511999999999",
+  preHandle: (value) => value.replace(/[\s().-]/g, "")
+});
+export const Url = propertyOf({
+  name: "url",
+  schema: Type.String({ format: "url", maxLength: 2048 }),
+  default: "https://example.com",
+  preHandle: (value) => value.trim()
+});
+export const Ip = propertyOf({
+  name: "ip",
+  schema: Type.Union([
+    Type.String({ format: "ipv4" }),
+    Type.String({ format: "ipv6" })
+  ]),
+  default: "127.0.0.1",
+  preHandle: (value) => value.trim()
+});

package/dist/std/properties/enum.js

@@ -0,0 +1,26 @@
+import { Type } from "typebox";
+import { recordPropertyLineage } from "../../core/property/lineage.js";
+import { propertyOf } from "../../core/property/property.js";
+export function enumOf(values, {
+  name = "enum",
+  optional,
+  default: _default = values[0]
+} = {}) {
+  const Enum = propertyOf({
+    name,
+    schema: Type.Enum(values),
+    optional,
+    default: _default
+  });
+  recordPropertyLineage(Enum, {
+    kind: "factory",
+    factory: "enumOf",
+    args: Object.freeze({
+      values: Object.freeze([...values]),
+      ...name === "enum" ? {} : { name },
+      ...optional ? { optional: true } : {},
+      ..._default === values[0] ? {} : { default: _default }
+    })
+  });
+  return Enum;
+}

package/dist/std/properties/exceptions.js

@@ -0,0 +1,14 @@
+import { ExceptionLayers } from "../../core/exception/enums/exception-layers.js";
+import { exceptionOf } from "../../core/exception/exception.js";
+import { markExported } from "../../core/exception/exported.js";
+export const InvalidJsonData = exceptionOf({
+  layer: ExceptionLayers.Property,
+  name: "InvalidJsonData",
+  message: ({ issues }, source) => `Invalid JSON data for "${source}": ${issues.map((issue) => `${issue.path.length === 0 ? "/" : `/${issue.path.join("/")}`}: ${issue.message}`).join("; ")}`
+});
+export const InvalidJsonSchema = exceptionOf({
+  layer: ExceptionLayers.Schema,
+  name: "InvalidJsonSchema",
+  message: (_, source) => `The schema of "${source}" is not a JSON Schema.`
+});
+markExported(InvalidJsonData, InvalidJsonSchema);

package/dist/std/properties/headless.js

@@ -0,0 +1,45 @@
+import { Type } from "typebox";
+import { Meta } from "typebox/schema";
+import { InvalidPropertyValue } from "../../core/property/exceptions.js";
+import { propertyOf } from "../../core/property/property.js";
+import { schemaOf } from "../../core/schema/schema.js";
+const JSON_SCHEMA = Type.Unsafe({
+  type: "object",
+  allOf: [Meta["https://json-schema.org/draft/2020-12/schema"]]
+});
+
+export class SchemaProperty extends propertyOf({
+  name: "schema",
+  schema: JSON_SCHEMA,
+  default: Type.String()
+}) {
+  compiled;
+  static deserialize(json) {
+    let value;
+    try {
+      value = JSON.parse(json);
+    } catch (error) {
+      throw new InvalidPropertyValue({
+        source: "schema",
+        details: { errors: [error.message] }
+      });
+    }
+    return new SchemaProperty(value);
+  }
+  serialize() {
+    return JSON.stringify(this.value);
+  }
+  match(data) {
+    return this.toSchema().match(data);
+  }
+  errors(data) {
+    return this.toSchema().errors(data);
+  }
+  toSchema() {
+    if (!this.compiled) {
+      const Schema = schemaOf("schema", this.value);
+      this.compiled = new Schema;
+    }
+    return this.compiled;
+  }
+}

package/dist/std/properties/identity.js

@@ -0,0 +1,28 @@
+import slugify from "slugify";
+import { Type } from "typebox";
+import { propertyOf } from "../../core/property/property.js";
+import { generateId } from "../runtime.js";
+const UUID_V7 = "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$";
+
+export class Id extends propertyOf({
+  name: "id",
+  schema: Type.String({ pattern: UUID_V7 }),
+  default: "01a173d2-051c-77bb-8166-a371e999573e",
+  preHandle: (value) => value.toLowerCase()
+}) {
+  static generate() {
+    return new Id(generateId());
+  }
+}
+
+export class Slug extends propertyOf({
+  name: "slug",
+  schema: Type.String({
+    pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+    maxLength: 255
+  }),
+  default: "demo-slug",
+  unique: true,
+  preHandle: (value) => slugify(value, { lower: true, strict: true, trim: true })
+}) {
+}

package/dist/std/properties/json.js

@@ -0,0 +1,161 @@
+import { Type } from "typebox";
+import { Meta } from "typebox/schema";
+import Value from "typebox/value";
+import { recordPropertyLineage } from "../../core/property/lineage.js";
+import { propertyOf } from "../../core/property/property.js";
+import { InvalidJsonData, InvalidJsonSchema } from "./exceptions.js";
+function notJson(value, path = [], ancestors = []) {
+  if (value === null)
+    return;
+  switch (typeof value) {
+    case "string":
+    case "boolean":
+      return;
+    case "number":
+      return Number.isFinite(value) ? undefined : { path, message: `is not JSON (${value})` };
+    case "object":
+      break;
+    default:
+      return { path, message: `is not JSON (${typeof value})` };
+  }
+  if (ancestors.includes(value))
+    return { path, message: "is circular" };
+  const inner = [...ancestors, value];
+  if (Array.isArray(value)) {
+    for (let index = 0;index < value.length; index++) {
+      const found = notJson(value[index], [...path, index], inner);
+      if (found)
+        return found;
+    }
+    return;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    return {
+      path,
+      message: `is not JSON (an instance of ${prototype?.constructor?.name ?? "a class"})`
+    };
+  }
+  for (const [key, item] of Object.entries(value)) {
+    const found = notJson(item, [...path, key], inner);
+    if (found)
+      return found;
+  }
+  return;
+}
+const JSON_SCHEMA = Type.Unsafe({
+  type: "object",
+  allOf: [Meta["https://json-schema.org/draft/2020-12/schema"]]
+});
+const checked = new WeakSet;
+function assertJsonSchema(schema, source) {
+  if (typeof schema === "object" && schema !== null && checked.has(schema)) {
+    return schema;
+  }
+  if (!Value.Check(JSON_SCHEMA, schema)) {
+    throw new InvalidJsonSchema({ source });
+  }
+  checked.add(schema);
+  return schema;
+}
+function pathOf(pointer) {
+  if (pointer === "")
+    return [];
+  return pointer.slice(1).split("/").map((segment) => segment.replaceAll("~1", "/").replaceAll("~0", "~")).map((segment) => /^(?:0|[1-9][0-9]*)$/.test(segment) ? +segment : segment);
+}
+function issuesOfErrors(errors, source) {
+  const issues = [];
+  const add = (path, code, message) => {
+    issues.push({ path, code, message, source });
+  };
+  for (const error of errors) {
+    const path = pathOf(error.instancePath);
+    const keys = (name) => Array.isArray(error.params[name]) ? error.params[name] : [];
+    if (error.keyword === "required") {
+      for (const key of keys("requiredProperties")) {
+        add([...path, key], "required", "is required");
+      }
+    } else if (error.keyword === "additionalProperties") {
+      for (const key of keys("additionalProperties")) {
+        add([...path, key], "undeclared_key", "is not declared");
+      }
+    } else if (!(error.keyword === "boolean" && error.schemaPath.endsWith("/additionalProperties"))) {
+      add(path, error.keyword === "type" ? "invalid_type" : "invalid_value", error.message);
+    }
+  }
+  return issues;
+}
+export function jsonSchemaIssues(schema, value, { source = "json" } = {}) {
+  const checkedSchema = assertJsonSchema(schema, source);
+  const found = notJson(value);
+  if (found) {
+    return [
+      {
+        path: found.path,
+        code: "invalid_value",
+        message: found.message,
+        source
+      }
+    ];
+  }
+  if (Value.Check(checkedSchema, value))
+    return [];
+  return issuesOfErrors(Value.Errors(checkedSchema, value), source);
+}
+export function checkJsonSchema(schema, value, options = {}) {
+  const issues = jsonSchemaIssues(schema, value, options);
+  if (issues.length > 0) {
+    throw new InvalidJsonData({
+      source: options.source ?? "json",
+      details: { issues }
+    });
+  }
+  return value;
+}
+function demoOf(schema) {
+  try {
+    return Value.Create(schema);
+  } catch {
+    return;
+  }
+}
+function assertJson(value) {
+  const found = notJson(value);
+  if (found) {
+    throw new Error(`${found.path.length === 0 ? "" : `/${found.path.join("/")}: `}${found.message}`);
+  }
+  return value;
+}
+export const JsonProperty = propertyOf({
+  name: "json",
+  schema: Type.Unsafe({}),
+  default: {},
+  preHandle: assertJson
+});
+export function jsonOf({
+  schema,
+  name = "json",
+  optional,
+  default: _default
+}) {
+  assertJsonSchema(schema, name);
+  const made = _default ?? demoOf(schema);
+  const Json = propertyOf({
+    name,
+    schema,
+    optional,
+    ...made !== undefined && Value.Check(schema, made) ? { default: made } : {},
+    preHandle: assertJson
+  });
+  recordPropertyLineage(Json, {
+    kind: "factory",
+    factory: "jsonOf",
+    args: Object.freeze({
+      schema,
+      ...name === "json" ? {} : { name },
+      ...optional ? { optional: true } : {},
+      ..._default === undefined ? {} : { default: _default }
+    })
+  });
+  return Json;
+}

package/dist/std/properties/password.js

@@ -0,0 +1,79 @@
+import { Type } from "typebox";
+import { InvalidPropertyValue } from "../../core/property/exceptions.js";
+import { PropertyInput } from "../../core/property/input.js";
+import { propertyOf } from "../../core/property/property.js";
+import { currentHasher, verifySyncWithCurrent } from "../runtime.js";
+const PASSWORD_MIN_LENGTH = 7;
+export const PASSWORD_MAX_LENGTH = 128;
+const PASSWORD_SPECIAL_CHARACTERS = "!@#$%^&*()-_=+[]{}|\\;:'\",.<>/?`~";
+const ARGON2_HASH = "^\\$argon2(id|i|d)\\$v=\\d+\\$m=\\d+,t=\\d+,p=\\d+\\$[A-Za-z0-9+/]+\\$[A-Za-z0-9+/]+$";
+const DEMO_HASH = "$argon2id$v=19$m=65536,t=2,p=1$YO5NNmxyK9+adO95GxWsAaUX4TULmT3IGhTYfpshXl0$/C89OCh7bhDY2cR2UkgvOV3dPlkghNLhv/DJsdopwMo";
+export function isPasswordHash(value) {
+  return new RegExp(ARGON2_HASH).test(value);
+}
+export function passwordIssues(value) {
+  const issues = [];
+  if (value.length < PASSWORD_MIN_LENGTH) {
+    issues.push(`must have at least ${PASSWORD_MIN_LENGTH} characters`);
+  }
+  if (value.length > PASSWORD_MAX_LENGTH) {
+    issues.push(`must have at most ${PASSWORD_MAX_LENGTH} characters`);
+  }
+  if (!/[a-z]/.test(value))
+    issues.push("must contain a lowercase letter");
+  if (!/[A-Z]/.test(value))
+    issues.push("must contain an uppercase letter");
+  if (!/\d/.test(value))
+    issues.push("must contain a number");
+  if (![...value].some((char) => PASSWORD_SPECIAL_CHARACTERS.includes(char))) {
+    issues.push(`must contain a special character (${PASSWORD_SPECIAL_CHARACTERS})`);
+  }
+  return issues;
+}
+const escaped = PASSWORD_SPECIAL_CHARACTERS.replace(/[\\\]^-]/g, "\\$&");
+
+export class PlainPassword extends propertyOf({
+  name: "plainPassword",
+  schema: Type.String({
+    minLength: PASSWORD_MIN_LENGTH,
+    maxLength: PASSWORD_MAX_LENGTH,
+    pattern: `^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)(?=.*[${escaped}])`
+  }),
+  default: "Demo@123",
+  sensitive: true
+}) {
+}
+
+export class Password extends propertyOf({
+  name: "password",
+  schema: Type.String({ pattern: ARGON2_HASH }),
+  default: DEMO_HASH,
+  sensitive: true
+}) {
+  static [PropertyInput] = {
+    accepts: PlainPassword,
+    convert: async (plain) => (await Password.hash(plain)).value
+  };
+  static async hash(plain) {
+    const issues = passwordIssues(plain);
+    if (issues.length > 0) {
+      throw new InvalidPropertyValue({
+        source: "password",
+        details: { errors: issues }
+      });
+    }
+    return new Password(await currentHasher().hash(plain));
+  }
+  verify(input) {
+    const hash = this.value;
+    if (hash === undefined)
+      return Promise.resolve(false);
+    return currentHasher().verify(input, hash);
+  }
+  verifySync(input) {
+    const hash = this.value;
+    if (hash === undefined)
+      return false;
+    return verifySyncWithCurrent(input, hash);
+  }
+}

package/dist/std/properties/primitives.d.ts

@@ -1,7 +1,11 @@
 import { Type } from "typebox";
+/** Any string. */
 export declare const StringProperty: import("../../index.js").PropertyClass<Type.TString, string>;
 /** A string that is not blank once trimmed. */
 export declare const Text: import("../../index.js").PropertyClass<Type.TString, string>;
+/** Any number. */
 export declare const NumberProperty: import("../../index.js").PropertyClass<Type.TNumber, number>;
+/** An integer. Narrow it with `Integer.with({ min, max })`. */
 export declare const Integer: import("../../index.js").PropertyClass<Type.TInteger, number>;
+/** A boolean. */
 export declare const BooleanProperty: import("../../index.js").PropertyClass<Type.TBoolean, boolean>;

package/dist/std/properties/primitives.js

@@ -0,0 +1,28 @@
+import { Type } from "typebox";
+import { propertyOf } from "../../core/property/property.js";
+export const StringProperty = propertyOf({
+  name: "string",
+  schema: Type.String(),
+  default: "demo"
+});
+export const Text = propertyOf({
+  name: "text",
+  schema: Type.String({ minLength: 1 }),
+  default: "Demo",
+  preHandle: (value) => value.trim()
+});
+export const NumberProperty = propertyOf({
+  name: "number",
+  schema: Type.Number(),
+  default: 0
+});
+export const Integer = propertyOf({
+  name: "integer",
+  schema: Type.Integer(),
+  default: 0
+});
+export const BooleanProperty = propertyOf({
+  name: "boolean",
+  schema: Type.Boolean(),
+  default: false
+});

package/dist/std/properties/time.js

@@ -0,0 +1,55 @@
+import { Type } from "typebox";
+import { propertyOf } from "../../core/property/property.js";
+const DEMO_DATE_TIME = "2026-01-01T00:00:00.000Z";
+function dateTimeOf({
+  name,
+  optional,
+  default: _default
+}) {
+  return class extends propertyOf({
+    name,
+    schema: Type.String({ format: "date-time" }),
+    optional,
+    default: _default
+  }) {
+    static now() {
+      return new this(new Date().toISOString());
+    }
+  };
+}
+
+export class DateTime extends dateTimeOf({
+  name: "dateTime",
+  default: DEMO_DATE_TIME
+}) {
+}
+export const DateProperty = propertyOf({
+  name: "date",
+  schema: Type.String({ format: "date" }),
+  default: "2026-01-01"
+});
+
+export class CreatedAt extends dateTimeOf({
+  name: "createdAt",
+  default: DEMO_DATE_TIME
+}) {
+}
+
+export class UpdatedAt extends dateTimeOf({
+  name: "updatedAt",
+  optional: true,
+  default: DEMO_DATE_TIME
+}) {
+}
+
+export class DeletedAt extends dateTimeOf({
+  name: "deletedAt",
+  optional: true
+}) {
+}
+
+export class ExpiresAt extends dateTimeOf({
+  name: "expiresAt",
+  default: DEMO_DATE_TIME
+}) {
+}