Files
start-os/sdk/base/lib/util/Drop.ts
Aiden McClelland f2142f0bb3 add documentation for ai agents (#3115)
* add documentation for ai agents

* docs: consolidate CLAUDE.md and CONTRIBUTING.md, add style guidelines

- Refactor CLAUDE.md to reference CONTRIBUTING.md for build/test/format info
- Expand CONTRIBUTING.md with comprehensive build targets, env vars, and testing
- Add code style guidelines section with conventional commits
- Standardize SDK prettier config to use single quotes (matching web)
- Add project-level Claude Code settings to disable co-author attribution

* style(sdk): apply prettier with single quotes

Run prettier across sdk/base and sdk/package to apply the
standardized quote style (single quotes matching web).

* docs: add USER.md for per-developer TODO filtering

- Add agents/USER.md to .gitignore (contains user identifier)
- Document session startup flow in CLAUDE.md:
  - Create USER.md if missing, prompting for identifier
  - Filter TODOs by @username tags
  - Offer relevant TODOs on session start

* docs: add i18n documentation task to agent TODOs

* docs: document i18n ID patterns in core/

Add agents/i18n-patterns.md covering rust-i18n setup, translation file
format, t!() macro usage, key naming conventions, and locale selection.
Remove completed TODO item and add reference in CLAUDE.md.

* chore: clarify that all builds work on any OS with Docker
2026-02-06 00:10:16 +01:00

154 lines
4.8 KiB
TypeScript

const dropId: unique symbol = Symbol('id')
export type DropRef = { [dropId]: number }
export abstract class Drop {
private static weak: { [id: number]: Drop } = {}
private static registry = new FinalizationRegistry((id: number) => {
const weak = Drop.weak[id]
if (weak) weak.drop()
})
private static idCtr: number = 0
private dropId?: number
private dropRef?: DropRef | WeakRef<DropRef>
protected constructor() {
this.dropId = Drop.idCtr++
this.dropRef = { [dropId]: this.dropId }
const weak = this.weak()
Drop.weak[this.dropId] = weak
Drop.registry.register(this.dropRef, this.dropId, this.dropRef)
return new Proxy(this, {
set(target: any, prop, value) {
if (prop === 'dropRef' || prop == 'dropId') return false
target[prop] = value
;(weak as any)[prop] = value
return true
},
})
}
protected register() {}
private weak(): this {
const weak = Object.assign(Object.create(Object.getPrototypeOf(this)), this)
if (this.dropRef) weak.ref = new WeakRef(this.dropRef)
return weak
}
abstract onDrop(): void
drop(): void {
if (!this.dropRef || !this.dropId) return
this.onDrop()
this.leak()
}
leak(): this {
if (!this.dropRef || !this.dropId) return this
Drop.registry.unregister(this.dropRef)
delete Drop.weak[this.dropId]
delete this.dropRef
delete this.dropId
return this
}
}
export class DropPromise<T> implements Promise<T> {
private static dropFns: { [id: number]: () => void } = {}
private static registry = new FinalizationRegistry((id: number) => {
const drop = DropPromise.dropFns[id]
if (drop) {
drop()
delete DropPromise.dropFns[id]
}
})
private static idCtr: number = 0
private dropId: number
private dropRef: DropRef;
[Symbol.toStringTag] = 'DropPromise'
private constructor(
private readonly promise: Promise<T>,
dropFnOrRef?: (() => void) | DropRef,
) {
if (dropFnOrRef && dropId in dropFnOrRef) {
this.dropId = dropFnOrRef[dropId]
this.dropRef = dropFnOrRef
return
}
this.dropId = DropPromise.idCtr++
this.dropRef = { [dropId]: this.dropId }
if (dropFnOrRef) DropPromise.dropFns[this.dropId] = dropFnOrRef
DropPromise.registry.register(this.dropRef, this.dropId, this.dropRef)
}
static of<T>(promise: Promise<T>, dropFn?: () => void): DropPromise<T> {
return new DropPromise(promise, dropFn)
}
static ref<T>(promise: Promise<T>, dropRef: DropRef): DropPromise<T> {
return new DropPromise(promise, dropRef)
}
then<TResult1 = T, TResult2 = never>(
onfulfilled?:
| ((value: T) => TResult1 | PromiseLike<TResult1>)
| null
| undefined,
onrejected?:
| ((reason: any) => TResult2 | PromiseLike<TResult2>)
| null
| undefined,
): Promise<TResult1 | TResult2> {
return DropPromise.ref(
this.promise.then(onfulfilled, onrejected),
this.dropRef,
)
}
catch<TResult = never>(
onrejected?:
| ((reason: any) => TResult | PromiseLike<TResult>)
| null
| undefined,
): Promise<T | TResult> {
return DropPromise.ref(this.promise.catch(onrejected), this.dropRef)
}
finally(onfinally?: (() => void) | null | undefined): Promise<T> {
return DropPromise.ref(this.promise.finally(onfinally), this.dropRef)
}
}
export class DropGenerator<T = unknown, TReturn = any, TNext = unknown>
implements AsyncGenerator<T, TReturn, TNext>
{
private static dropFns: { [id: number]: () => void } = {}
private static registry = new FinalizationRegistry((id: number) => {
const drop = DropGenerator.dropFns[id]
if (drop) {
drop()
delete DropGenerator.dropFns[id]
}
})
private static idCtr: number = 0
private dropId: number
private dropRef: DropRef;
[Symbol.asyncIterator] = () => this
private constructor(
private readonly generator: AsyncGenerator<T, TReturn, TNext>,
dropFn?: () => void,
) {
this.dropId = DropGenerator.idCtr++
this.dropRef = { [dropId]: this.dropId }
if (dropFn) DropGenerator.dropFns[this.dropId] = dropFn
DropGenerator.registry.register(this.dropRef, this.dropId, this.dropRef)
}
static of<T, TReturn, TNext>(
generator: AsyncGenerator<T, TReturn, TNext>,
dropFn?: () => void,
): DropGenerator<T, TReturn, TNext> {
return new DropGenerator(generator, dropFn)
}
next(...args: [] | [TNext]): Promise<IteratorResult<T, TReturn>> {
return DropPromise.ref(this.generator.next(...args), this.dropRef)
}
return(
value: TReturn | PromiseLike<TReturn>,
): Promise<IteratorResult<T, TReturn>> {
return DropPromise.ref(this.generator.return(value), this.dropRef)
}
throw(e: any): Promise<IteratorResult<T, TReturn>> {
return DropPromise.ref(this.generator.throw(e), this.dropRef)
}
}