@starkeep/protocol-primitives 0.1.0

package/dist/index.cjs

@@ -0,0 +1,627 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  APP_GRANTABLE_CATEGORIES: () => APP_GRANTABLE_CATEGORIES,
+  CATEGORIES: () => CATEGORIES,
+  CATEGORY_IDS: () => CATEGORY_IDS,
+  ConflictError: () => ConflictError,
+  EXTENSIONS: () => EXTENSIONS,
+  KNOWN_EXTENSIONS: () => KNOWN_EXTENSIONS,
+  NotFoundError: () => NotFoundError,
+  StarkeepError: () => StarkeepError,
+  ValidationError: () => ValidationError,
+  ZERO_HLC: () => ZERO_HLC,
+  appSyncableObjectKey: () => appSyncableObjectKey,
+  categoryOf: () => categoryOf,
+  compareHLC: () => compareHLC,
+  createDataRecord: () => createDataRecord,
+  createHLCClock: () => createHLCClock,
+  createStarkeepId: () => createStarkeepId,
+  createTypeRegistry: () => createTypeRegistry,
+  dataRecordObjectKey: () => dataRecordObjectKey,
+  dataRecordSchema: () => dataRecordSchema,
+  deserializeHLC: () => deserializeHLC,
+  err: () => err,
+  generateId: () => generateId,
+  generateIdAt: () => generateIdAt,
+  getCategory: () => getCategory,
+  isCategoryId: () => isCategoryId,
+  isStarkeepId: () => isStarkeepId,
+  maxHLC: () => maxHLC,
+  ok: () => ok,
+  pgMetadataDdl: () => pgMetadataDdl,
+  pgMetadataTableName: () => pgMetadataTableName,
+  serializeHLC: () => serializeHLC,
+  sqliteMetadataDdl: () => sqliteMetadataDdl,
+  sqliteMetadataTableName: () => sqliteMetadataTableName,
+  validateDataRecord: () => validateDataRecord
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/identifiers/types.ts
+function createStarkeepId(value) {
+  return value;
+}
+function isStarkeepId(value) {
+  return typeof value === "string" && value.length === 26;
+}
+
+// src/identifiers/ulid.ts
+var import_ulidx = require("ulidx");
+var monotonic = (0, import_ulidx.monotonicFactory)();
+function generateId() {
+  return createStarkeepId(monotonic());
+}
+function generateIdAt(timestamp) {
+  return createStarkeepId((0, import_ulidx.ulid)(timestamp));
+}
+
+// src/hlc/clock.ts
+function createHLCClock(options) {
+  const { nodeId, wallClockFunction = Date.now, initialState, onTick } = options;
+  let lastWallTime = initialState?.wallTime ?? 0;
+  let lastCounter = initialState?.counter ?? 0;
+  function emit() {
+    if (onTick) onTick({ wallTime: lastWallTime, counter: lastCounter });
+  }
+  function now() {
+    const physicalTime = wallClockFunction();
+    if (physicalTime > lastWallTime) {
+      lastWallTime = physicalTime;
+      lastCounter = 0;
+    } else {
+      lastCounter++;
+    }
+    emit();
+    return { wallTime: lastWallTime, counter: lastCounter, nodeId };
+  }
+  function send() {
+    return now();
+  }
+  function receive(remote) {
+    const physicalTime = wallClockFunction();
+    if (physicalTime > lastWallTime && physicalTime > remote.wallTime) {
+      lastWallTime = physicalTime;
+      lastCounter = 0;
+    } else if (remote.wallTime > lastWallTime) {
+      lastWallTime = remote.wallTime;
+      lastCounter = remote.counter + 1;
+    } else if (lastWallTime === remote.wallTime) {
+      lastCounter = Math.max(lastCounter, remote.counter) + 1;
+    } else {
+      lastCounter++;
+    }
+    emit();
+    return { wallTime: lastWallTime, counter: lastCounter, nodeId };
+  }
+  return { now, send, receive };
+}
+
+// src/hlc/compare.ts
+var ZERO_HLC = { wallTime: 0, counter: 0, nodeId: "" };
+function compareHLC(a, b) {
+  if (a.wallTime < b.wallTime) return -1;
+  if (a.wallTime > b.wallTime) return 1;
+  if (a.counter < b.counter) return -1;
+  if (a.counter > b.counter) return 1;
+  if (a.nodeId < b.nodeId) return -1;
+  if (a.nodeId > b.nodeId) return 1;
+  return 0;
+}
+function maxHLC(a, b) {
+  return compareHLC(a, b) >= 0 ? a : b;
+}
+
+// src/hlc/serialize.ts
+var SEPARATOR = ":";
+function serializeHLC(timestamp) {
+  const wallTimeHex = timestamp.wallTime.toString(16).padStart(12, "0");
+  const counterHex = timestamp.counter.toString(16).padStart(4, "0");
+  return `${wallTimeHex}${SEPARATOR}${counterHex}${SEPARATOR}${timestamp.nodeId}`;
+}
+function deserializeHLC(serializedString) {
+  const parts = serializedString.split(SEPARATOR);
+  if (parts.length !== 3) {
+    throw new Error(`Invalid HLC timestamp string: ${serializedString}`);
+  }
+  return {
+    wallTime: parseInt(parts[0], 16),
+    counter: parseInt(parts[1], 16),
+    nodeId: parts[2]
+  };
+}
+
+// src/records/builders.ts
+function createDataRecord(input, clock) {
+  const now = clock.now();
+  return {
+    id: generateId(),
+    kind: "data",
+    type: input.type,
+    createdAt: now,
+    updatedAt: now,
+    ownerId: input.ownerId,
+    deletedAt: null,
+    version: 1,
+    contentHash: input.contentHash,
+    objectStorageKey: input.objectStorageKey,
+    mimeType: input.mimeType,
+    sizeBytes: input.sizeBytes,
+    originalFilename: input.originalFilename ?? null,
+    originAppId: input.originAppId,
+    parentId: input.parentId ?? null
+  };
+}
+
+// src/schema/registry.ts
+function createTypeRegistry() {
+  const types = /* @__PURE__ */ new Map();
+  return {
+    register(definition) {
+      const key = `${definition.namespace}:${definition.name}`;
+      if (types.has(key)) {
+        throw new Error(`Type "${key}" is already registered`);
+      }
+      types.set(key, definition);
+    },
+    get(namespace, name) {
+      return types.get(`${namespace}:${name}`);
+    },
+    getByKey(key) {
+      return types.get(key);
+    },
+    has(namespace, name) {
+      return types.has(`${namespace}:${name}`);
+    },
+    list() {
+      return Array.from(types.values());
+    }
+  };
+}
+
+// src/schema/validator.ts
+var v = __toESM(require("valibot"), 1);
+var hlcTimestampSchema = v.object({
+  wallTime: v.pipe(v.number(), v.integer(), v.minValue(0)),
+  counter: v.pipe(v.number(), v.integer(), v.minValue(0)),
+  nodeId: v.pipe(v.string(), v.minLength(1))
+});
+var baseRecordSchema = v.object({
+  id: v.pipe(v.string(), v.length(26)),
+  type: v.pipe(v.string(), v.minLength(1)),
+  createdAt: hlcTimestampSchema,
+  updatedAt: hlcTimestampSchema,
+  ownerId: v.pipe(v.string(), v.minLength(1)),
+  deletedAt: v.nullable(hlcTimestampSchema),
+  version: v.pipe(v.number(), v.integer(), v.minValue(1))
+});
+var dataRecordSchema = v.object({
+  ...baseRecordSchema.entries,
+  kind: v.literal("data"),
+  contentHash: v.pipe(v.string(), v.minLength(1)),
+  objectStorageKey: v.pipe(v.string(), v.minLength(1)),
+  mimeType: v.pipe(v.string(), v.minLength(1)),
+  sizeBytes: v.pipe(v.number(), v.integer(), v.minValue(0)),
+  originalFilename: v.nullable(v.string()),
+  originAppId: v.pipe(v.string(), v.minLength(1)),
+  parentId: v.nullable(v.string())
+});
+function validateDataRecord(data) {
+  return v.safeParse(dataRecordSchema, data);
+}
+
+// src/types/errors.ts
+var StarkeepError = class extends Error {
+  constructor(message, code, cause) {
+    super(message);
+    this.code = code;
+    this.cause = cause;
+    this.name = "StarkeepError";
+  }
+};
+var ValidationError = class extends StarkeepError {
+  constructor(message, cause) {
+    super(message, "VALIDATION_ERROR", cause);
+    this.name = "ValidationError";
+  }
+};
+var NotFoundError = class extends StarkeepError {
+  constructor(entity, id) {
+    super(`${entity} not found: ${id}`, "NOT_FOUND");
+    this.name = "NotFoundError";
+  }
+};
+var ConflictError = class extends StarkeepError {
+  constructor(message) {
+    super(message, "CONFLICT");
+    this.name = "ConflictError";
+  }
+};
+
+// src/types/common.ts
+function ok(value) {
+  return { ok: true, value };
+}
+function err(error) {
+  return { ok: false, error };
+}
+
+// src/types/core-types.ts
+var IMAGE_METADATA_COLUMNS = [
+  { name: "width", type: "integer" },
+  { name: "height", type: "integer" },
+  { name: "color_space", type: "text" },
+  { name: "orientation", type: "integer" },
+  { name: "captured_at", type: "timestamp" },
+  { name: "camera_make", type: "text" },
+  { name: "camera_model", type: "text" },
+  { name: "lens_model", type: "text" },
+  { name: "f_number", type: "real" },
+  { name: "exposure_time", type: "text" },
+  { name: "iso", type: "integer" },
+  { name: "focal_length_mm", type: "real" },
+  { name: "gps_lat", type: "real" },
+  { name: "gps_lon", type: "real" }
+];
+var VIDEO_METADATA_COLUMNS = [
+  { name: "width", type: "integer" },
+  { name: "height", type: "integer" },
+  { name: "duration_ms", type: "bigint" },
+  { name: "frame_rate", type: "real" },
+  { name: "video_codec", type: "text" },
+  { name: "audio_codec", type: "text" },
+  { name: "bitrate", type: "bigint" },
+  { name: "captured_at", type: "timestamp" },
+  { name: "gps_lat", type: "real" },
+  { name: "gps_lon", type: "real" }
+];
+var AUDIO_METADATA_COLUMNS = [
+  { name: "duration_ms", type: "bigint" },
+  { name: "sample_rate", type: "integer" },
+  { name: "channels", type: "integer" },
+  { name: "bitrate", type: "bigint" },
+  { name: "codec", type: "text" },
+  { name: "title", type: "text" },
+  { name: "artist", type: "text" },
+  { name: "album", type: "text" },
+  { name: "track_number", type: "integer" },
+  { name: "year", type: "integer" },
+  { name: "genre", type: "text" }
+];
+var DOCUMENT_METADATA_COLUMNS = [
+  { name: "page_count", type: "integer" },
+  { name: "word_count", type: "integer" },
+  { name: "author", type: "text" },
+  { name: "title", type: "text" },
+  { name: "created_at", type: "timestamp" },
+  { name: "modified_at", type: "timestamp" },
+  { name: "language", type: "text" }
+];
+var TEXT_METADATA_COLUMNS = [
+  { name: "line_count", type: "integer" },
+  { name: "encoding", type: "text" }
+];
+var CODE_METADATA_COLUMNS = [
+  { name: "line_count", type: "integer" },
+  { name: "encoding", type: "text" }
+];
+var FONT_METADATA_COLUMNS = [
+  { name: "family", type: "text" },
+  { name: "subfamily", type: "text" },
+  { name: "weight", type: "integer" },
+  { name: "style", type: "text" },
+  { name: "format", type: "text" }
+];
+var ARCHIVE_METADATA_COLUMNS = [
+  { name: "entry_count", type: "integer" },
+  { name: "uncompressed_bytes", type: "bigint" },
+  { name: "compression", type: "text" }
+];
+var DATA_METADATA_COLUMNS = [
+  { name: "row_count", type: "bigint" },
+  { name: "column_count", type: "integer" },
+  { name: "schema_json", type: "text" }
+];
+var MODEL3D_METADATA_COLUMNS = [
+  { name: "vertex_count", type: "bigint" },
+  { name: "face_count", type: "bigint" },
+  { name: "has_textures", type: "boolean" },
+  { name: "has_animation", type: "boolean" }
+];
+var CATEGORIES = [
+  { id: "image", description: "Raster and vector still images. Bytes in object storage; metadata holds dimensions, capture time, EXIF, orientation.", metadataColumns: IMAGE_METADATA_COLUMNS },
+  { id: "video", description: "Moving-picture containers.", metadataColumns: VIDEO_METADATA_COLUMNS },
+  { id: "audio", description: "Sound-only containers.", metadataColumns: AUDIO_METADATA_COLUMNS },
+  { id: "document", description: "Office-suite and structured documents meant for human reading (incl. markdown, html, spreadsheets).", metadataColumns: DOCUMENT_METADATA_COLUMNS },
+  { id: "text", description: "Plain-text formats: prose, config, structured serialization.", metadataColumns: TEXT_METADATA_COLUMNS },
+  { id: "code", description: "Programming-language source files.", metadataColumns: CODE_METADATA_COLUMNS },
+  { id: "font", description: "Typeface files.", metadataColumns: FONT_METADATA_COLUMNS },
+  { id: "archive", description: "Compressed bundles.", metadataColumns: ARCHIVE_METADATA_COLUMNS },
+  { id: "data", description: "Tabular / columnar / embedded-DB data files.", metadataColumns: DATA_METADATA_COLUMNS },
+  { id: "model3d", description: "3D meshes and scenes.", metadataColumns: MODEL3D_METADATA_COLUMNS },
+  { id: "other", description: "Terminal catch-all for unmapped or extension-less files. Drive-only; no metadata table; no installable-app grants.", metadataColumns: [] }
+];
+var EXTENSIONS = {
+  // image
+  jpg: "image",
+  jpeg: "image",
+  png: "image",
+  gif: "image",
+  webp: "image",
+  heic: "image",
+  heif: "image",
+  avif: "image",
+  bmp: "image",
+  tiff: "image",
+  tif: "image",
+  svg: "image",
+  ico: "image",
+  // video
+  mp4: "video",
+  mov: "video",
+  m4v: "video",
+  avi: "video",
+  mkv: "video",
+  webm: "video",
+  mpg: "video",
+  mpeg: "video",
+  wmv: "video",
+  flv: "video",
+  // audio
+  mp3: "audio",
+  wav: "audio",
+  flac: "audio",
+  aac: "audio",
+  ogg: "audio",
+  oga: "audio",
+  opus: "audio",
+  m4a: "audio",
+  aiff: "audio",
+  wma: "audio",
+  // document
+  pdf: "document",
+  md: "document",
+  markdown: "document",
+  html: "document",
+  htm: "document",
+  doc: "document",
+  docx: "document",
+  xls: "document",
+  xlsx: "document",
+  ppt: "document",
+  pptx: "document",
+  odt: "document",
+  ods: "document",
+  odp: "document",
+  rtf: "document",
+  epub: "document",
+  pages: "document",
+  numbers: "document",
+  key: "document",
+  // text
+  txt: "text",
+  log: "text",
+  env: "text",
+  json: "text",
+  jsonc: "text",
+  xml: "text",
+  yaml: "text",
+  yml: "text",
+  toml: "text",
+  ini: "text",
+  conf: "text",
+  tex: "text",
+  rst: "text",
+  adoc: "text",
+  // code
+  js: "code",
+  mjs: "code",
+  cjs: "code",
+  ts: "code",
+  tsx: "code",
+  jsx: "code",
+  py: "code",
+  rb: "code",
+  go: "code",
+  rs: "code",
+  java: "code",
+  kt: "code",
+  swift: "code",
+  c: "code",
+  h: "code",
+  cpp: "code",
+  hpp: "code",
+  cs: "code",
+  php: "code",
+  sh: "code",
+  bash: "code",
+  zsh: "code",
+  fish: "code",
+  ps1: "code",
+  lua: "code",
+  r: "code",
+  sql: "code",
+  css: "code",
+  scss: "code",
+  sass: "code",
+  less: "code",
+  vue: "code",
+  svelte: "code",
+  dockerfile: "code",
+  gitignore: "code",
+  gitattributes: "code",
+  // font
+  ttf: "font",
+  otf: "font",
+  woff: "font",
+  woff2: "font",
+  eot: "font",
+  // archive
+  zip: "archive",
+  tar: "archive",
+  gz: "archive",
+  tgz: "archive",
+  bz2: "archive",
+  tbz2: "archive",
+  xz: "archive",
+  txz: "archive",
+  "7z": "archive",
+  rar: "archive",
+  zst: "archive",
+  // data
+  csv: "data",
+  tsv: "data",
+  parquet: "data",
+  arrow: "data",
+  feather: "data",
+  sqlite: "data",
+  sqlite3: "data",
+  db: "data",
+  jsonl: "data",
+  ndjson: "data",
+  hdf5: "data",
+  h5: "data",
+  orc: "data",
+  // model3d
+  obj: "model3d",
+  stl: "model3d",
+  gltf: "model3d",
+  glb: "model3d",
+  fbx: "model3d",
+  dae: "model3d",
+  "3ds": "model3d",
+  blend: "model3d",
+  ply: "model3d",
+  usd: "model3d",
+  usdz: "model3d"
+};
+var CATEGORY_IDS = CATEGORIES.map((c) => c.id);
+var APP_GRANTABLE_CATEGORIES = CATEGORY_IDS.filter(
+  (c) => c !== "other"
+);
+var KNOWN_EXTENSIONS = new Set(Object.keys(EXTENSIONS));
+function categoryOf(ext) {
+  const normalized = ext.toLowerCase().replace(/^\./, "");
+  return EXTENSIONS[normalized] ?? "other";
+}
+function getCategory(id) {
+  return CATEGORIES.find((c) => c.id === id);
+}
+function isCategoryId(id) {
+  return CATEGORIES.some((c) => c.id === id);
+}
+function pgColumnType(t) {
+  switch (t) {
+    case "integer":
+      return "integer";
+    case "bigint":
+      return "bigint";
+    case "real":
+      return "double precision";
+    case "text":
+      return "text";
+    case "timestamp":
+      return "timestamptz";
+    case "boolean":
+      return "boolean";
+  }
+}
+function sqliteColumnType(t) {
+  switch (t) {
+    case "integer":
+      return "INTEGER";
+    case "bigint":
+      return "INTEGER";
+    case "real":
+      return "REAL";
+    case "text":
+      return "TEXT";
+    case "timestamp":
+      return "TEXT";
+    case "boolean":
+      return "INTEGER";
+  }
+}
+function pgMetadataDdl(c) {
+  const cols = [
+    `         record_id   text PRIMARY KEY`,
+    ...c.metadataColumns.map((col) => {
+      const nullSuffix = col.nullable === false ? " NOT NULL" : "";
+      return `         ${col.name} ${pgColumnType(col.type)}${nullSuffix}`;
+    })
+  ];
+  return `CREATE TABLE IF NOT EXISTS ${pgMetadataTableName(c.id)} (
+${cols.join(",\n")}
+       )`;
+}
+function sqliteMetadataDdl(c) {
+  const cols = [
+    `      record_id TEXT PRIMARY KEY`,
+    ...c.metadataColumns.map((col) => {
+      const nullSuffix = col.nullable === false ? " NOT NULL" : "";
+      return `      ${col.name} ${sqliteColumnType(col.type)}${nullSuffix}`;
+    })
+  ];
+  return `CREATE TABLE IF NOT EXISTS ${sqliteMetadataTableName(c.id)} (
+${cols.join(",\n")}
+    )`;
+}
+function sqliteMetadataTableName(typeOrCategory) {
+  const category = isCategoryId(typeOrCategory) ? typeOrCategory : categoryOf(typeOrCategory);
+  return `shared_record_${category}_metadata`;
+}
+function pgMetadataTableName(typeOrCategory) {
+  const category = isCategoryId(typeOrCategory) ? typeOrCategory : categoryOf(typeOrCategory);
+  return `shared.record_${category}_metadata`;
+}
+
+// src/storage/object-keys.ts
+function dataRecordObjectKey(typeOrExt, contentHash) {
+  const shard = contentHash.slice(0, 2);
+  return `shared/${categoryOf(typeOrExt)}/${shard}/${contentHash}`;
+}
+function appSyncableObjectKey(appId, subKey) {
+  if (!appId || /[/\s]/.test(appId)) {
+    throw new Error(`appSyncableObjectKey: invalid appId ${JSON.stringify(appId)}`);
+  }
+  const prefix = `apps/${appId}/syncable/`;
+  const relative = subKey.startsWith(prefix) ? subKey.slice(prefix.length) : subKey;
+  if (relative.startsWith("/")) {
+    throw new Error(`appSyncableObjectKey: subKey must not start with "/" (got ${JSON.stringify(subKey)})`);
+  }
+  const segments = relative.split("/");
+  if (segments.some((s) => s === "..")) {
+    throw new Error(`appSyncableObjectKey: subKey must not contain ".." (got ${JSON.stringify(subKey)})`);
+  }
+  return `${prefix}${relative}`;
+}
+//# sourceMappingURL=index.cjs.map